{
  "openapi": "3.0.3",
  "info": {
    "title": "mapapi Address, Region and Road Distance API",
    "version": "1.8.0",
    "description": "Only published region data and authorized PAF data. Coordinate precision is postcode, never building. GET only; bounded keyset pagination. Source PAF address id and UDPRN are separate identifiers. Preserve id mapping across source updates."
  },
  "servers": [
    {
      "url": "https://api.mapapi.co.uk"
    }
  ],
  "components": {
    "securitySchemes": {
      "siteKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pc_<64 hex characters>"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "Geometry": {
        "type": "object",
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "Polygon",
              "MultiPolygon"
            ]
          },
          "coordinates": {
            "type": "array",
            "description": "RFC 7946 WGS84 [longitude,latitude], closed rings, maximum 50,000 vertices",
            "items": {
              "type": "array",
              "items": {}
            }
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "udprn": {
            "type": "string"
          },
          "formatted": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "postcode": {
            "type": "string"
          },
          "building_number": {
            "type": "string"
          },
          "building_name": {
            "type": "string"
          },
          "sub_building": {
            "type": "string"
          },
          "street": {
            "type": "string"
          },
          "post_town": {
            "type": "string"
          }
        }
      },
      "Region": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "parent_id": {
            "type": "integer",
            "nullable": true
          },
          "source": {
            "type": "string"
          },
          "source_id": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "published"
            ]
          },
          "version": {
            "type": "integer"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "geometry": {
            "$ref": "#/components/schemas/Geometry"
          },
          "attribution": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "source_date": {
            "type": "string",
            "nullable": true
          },
          "source_detail": {
            "type": "string"
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Postcode": {
        "type": "object",
        "required": [
          "postcode",
          "available",
          "precision",
          "latitude",
          "longitude",
          "delivery_eligible"
        ],
        "properties": {
          "postcode": {
            "type": "string"
          },
          "postcode_sector": {
            "type": "string",
            "nullable": true,
            "description": "Postcode Sector from the selected coordinates source row; null when no source row is available."
          },
          "postcode_district": {
            "type": "string",
            "nullable": true,
            "description": "Postcode District from the selected coordinates source row; null when no source row is available."
          },
          "postcode_area": {
            "type": "string",
            "nullable": true,
            "description": "Postcode Area from the selected coordinates source row; null when no source row is available."
          },
          "available": {
            "type": "boolean"
          },
          "precision": {
            "type": "string",
            "enum": [
              "postcode"
            ]
          },
          "latitude": {
            "type": "number",
            "nullable": true
          },
          "longitude": {
            "type": "number",
            "nullable": true
          },
          "reason": {
            "type": "string"
          },
          "delivery_eligible": {
            "nullable": true,
            "description": "Always null: delivery eligibility is decided by the shop."
          },
          "regions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Region"
            }
          },
          "source": {
            "type": "string"
          },
          "source_id": {
            "type": "integer",
            "nullable": true
          },
          "regions_next_cursor": {
            "type": "string",
            "nullable": true
          },
          "message": {
            "type": "string"
          },
          "coordinate_error": {
            "type": "string"
          },
          "pqi": {
            "type": "string",
            "nullable": true
          },
          "introduced": {
            "type": "string",
            "nullable": true
          },
          "retired": {
            "type": "string",
            "nullable": true
          },
          "updated_at": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "RoadDistance": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "mode": {
            "type": "string"
          },
          "distance_type": {
            "type": "string"
          },
          "coordinate_precision": {
            "type": "string"
          },
          "route_selection": {
            "type": "string",
            "enum": [
              "engine_recommended"
            ],
            "description": "The routing engine's recommended driving route; not a guarantee of shortest distance or fastest journey."
          },
          "provider": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "license_url": {
            "type": "string"
          },
          "distance_miles": {
            "type": "number",
            "minimum": 0
          },
          "distance_metres": {
            "type": "number",
            "minimum": 0
          },
          "duration_seconds": {
            "type": "number",
            "minimum": 0
          },
          "duration_minutes": {
            "type": "number",
            "minimum": 0
          },
          "live_traffic": {
            "type": "boolean"
          },
          "snapped_from": {
            "type": "object",
            "properties": {
              "longitude": {
                "type": "number"
              },
              "latitude": {
                "type": "number"
              },
              "snap_distance_metres": {
                "type": "number"
              }
            }
          },
          "snapped_to": {
            "type": "object",
            "properties": {
              "longitude": {
                "type": "number"
              },
              "latitude": {
                "type": "number"
              },
              "snap_distance_metres": {
                "type": "number"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/addresses": {
      "get": {
        "summary": "List addresses for one UK postcode",
        "description": "Requires addresses scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "postcode",
            "in": "query",
            "required": true,
            "description": "Complete UK postcode, e.g. AB10 1AU.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Optional building/name filter within the postcode, <=100 bytes.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Use next_cursor from previous response.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Address"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/addresses/{id}": {
      "get": {
        "summary": "Selected address with postcode coordinate and matching regions",
        "description": "Requires addresses scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "addresses"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/Address"
                        },
                        {
                          "type": "object",
                          "properties": {
                            "coordinate": {
                              "$ref": "#/components/schemas/Postcode",
                              "nullable": true
                            },
                            "regions": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/Region"
                              }
                            },
                            "manual_entry_allowed": {
                              "type": "boolean"
                            }
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/postcodes/{postcode}": {
      "get": {
        "summary": "Return available coordinate or explicit missing reason",
        "description": "Requires postcodes scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "postcodes"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "postcode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Postcode"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/regions": {
      "get": {
        "summary": "Search published region metadata",
        "description": "Requires regions scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "regions"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "parent_id",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_geometry",
            "in": "query",
            "required": false,
            "description": "1 includes boundaries and caps each page at 5 (payload size can reduce a page further).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Use next_cursor from previous response.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Region"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/regions/{id}": {
      "get": {
        "summary": "Get published boundary and hierarchy metadata",
        "description": "Requires regions scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "regions"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Region"
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/regions/{id}/children": {
      "get": {
        "summary": "List published direct children; parent remains independent",
        "description": "Requires regions scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "regions"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Use next_cursor from previous response.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Region"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/regions/lookup": {
      "get": {
        "summary": "Regions containing a point including shared boundary points",
        "description": "Requires regions scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "regions"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": true,
            "description": "",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Use next_cursor from previous response.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Region"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/regions/changes": {
      "get": {
        "summary": "Immutable published upsert/delete events with snapshot pagination",
        "description": "Requires regions scope. Server-to-server only. Send a Bearer token in Authorization; never expose it to the browser.",
        "tags": [
          "regions"
        ],
        "security": [
          {
            "siteKey": []
          }
        ],
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Committed sequence or ISO8601 datetime. Start 0 for a full bootstrap. Prefer sequence for ongoing sync.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Opaque next_cursor: use it unchanged and finish every page before saving sync_cursor.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "sequence": {
                            "type": "integer"
                          },
                          "region_id": {
                            "type": "integer"
                          },
                          "operation": {
                            "type": "string",
                            "enum": [
                              "upsert",
                              "delete"
                            ]
                          },
                          "changed_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "region": {
                            "$ref": "#/components/schemas/Region",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": "string",
                          "nullable": true
                        },
                        "sync_cursor": {
                          "type": "string",
                          "description": "Committed sequence high-water mark for the next synchronization; only use after all pages finish."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            }
          },
          "503": {
            "description": "Request denied or unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/routes/distance": {
      "get": {
        "summary": "Driving road distance between two postcodes",
        "description": "Requires routes scope and PAF licence confirmation. Returns the engine-recommended driving route between snapped postcode points, not building entrances. No shortest-distance or fastest-journey guarantee; no live traffic or straight-line fallback.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Road distance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/RoadDistance"
                    },
                    "meta": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing scope or blocked IP",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Invalid postcode, missing coordinates or no route",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Invalid engine response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Not configured or PAF confirmation missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "504": {
            "description": "Engine timeout",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "security": [
          {
            "siteKey": []
          }
        ]
      }
    }
  },
  "security": [
    {
      "siteKey": []
    }
  ]
}