{
  "openapi": "3.1.0",
  "info": {
    "title": "Geoapify Boundaries API",
    "version": "0.1.0",
    "description": "OpenAPI specification for retrieving administrative, postal, political, and related boundaries."
  },
  "servers": [
    {
      "url": "https://api.geoapify.com/v1"
    }
  ],
  "tags": [
    {
      "name": "Boundaries",
      "description": "Retrieve boundaries related to a place or location."
    }
  ],
  "paths": {
    "/boundaries/part-of": {
      "get": {
        "tags": [
          "Boundaries"
        ],
        "operationId": "getBoundariesPartOf",
        "summary": "Find boundaries containing a place",
        "description": "Returns boundaries that contain the provided place. Provide either id, lat/lon, or osm_id/osm_type.",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "description": "Geoapify API key.",
            "schema": {
              "type": "string"
            },
            "example": "YOUR_API_KEY"
          },
          {
            "name": "id",
            "in": "query",
            "required": false,
            "description": "Geoapify place identifier.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 2048
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Latitude. Must be used together with lon when id is not provided.",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "example": 51.113
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "description": "Longitude. Must be used together with lat when id is not provided.",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "example": -1.1536
          },
          {
            "name": "osm_id",
            "in": "query",
            "required": false,
            "description": "OpenStreetMap object identifier. Must be used together with osm_type.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "osm_type",
            "in": "query",
            "required": false,
            "description": "OpenStreetMap object type. Must be used together with osm_id.",
            "schema": {
              "type": "string",
              "enum": [
                "r",
                "w",
                "n"
              ]
            }
          },
          {
            "name": "boundaries",
            "in": "query",
            "required": false,
            "description": "Boundary types to return. Multiple values are comma-separated.",
            "schema": {
              "type": "array",
              "minItems": 1,
              "maxItems": 10,
              "items": {
                "type": "string",
                "enum": [
                  "administrative",
                  "postal_code",
                  "political",
                  "low_emission_zone",
                  "public_transport",
                  "traditional",
                  "timezone",
                  "religious_administration",
                  "religious",
                  "place",
                  "neighborhood",
                  "region",
                  "municipality",
                  "barony",
                  "town",
                  "health",
                  "historic",
                  "historic:administrative"
                ]
              }
            },
            "style": "form",
            "explode": false,
            "example": [
              "political",
              "administrative"
            ]
          },
          {
            "name": "geometry",
            "in": "query",
            "required": false,
            "description": "Optional geometry output mode.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 50
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Result language as a supported two-letter language code.",
            "schema": {
              "type": "string",
              "enum": [
                "ab",
                "aa",
                "af",
                "ak",
                "sq",
                "am",
                "ar",
                "an",
                "hy",
                "as",
                "av",
                "ae",
                "ay",
                "az",
                "bm",
                "ba",
                "eu",
                "be",
                "bn",
                "bh",
                "bi",
                "bs",
                "br",
                "bg",
                "my",
                "ca",
                "ch",
                "ce",
                "ny",
                "zh",
                "cv",
                "kw",
                "co",
                "cr",
                "hr",
                "cs",
                "da",
                "dv",
                "nl",
                "en",
                "eo",
                "et",
                "ee",
                "fo",
                "fj",
                "fi",
                "fr",
                "ff",
                "gl",
                "ka",
                "de",
                "el",
                "gn",
                "gu",
                "ht",
                "ha",
                "he",
                "hz",
                "hi",
                "ho",
                "hu",
                "ia",
                "id",
                "ie",
                "ga",
                "ig",
                "ik",
                "io",
                "is",
                "it",
                "iu",
                "ja",
                "jv",
                "kl",
                "kn",
                "kr",
                "ks",
                "kk",
                "km",
                "ki",
                "rw",
                "ky",
                "kv",
                "kg",
                "ko",
                "ku",
                "kj",
                "la",
                "lb",
                "lg",
                "li",
                "ln",
                "lo",
                "lt",
                "lu",
                "lv",
                "gv",
                "mk",
                "mg",
                "ms",
                "ml",
                "mt",
                "mi",
                "mr",
                "mh",
                "mn",
                "na",
                "nv",
                "nb",
                "nd",
                "ne",
                "ng",
                "nn",
                "no",
                "ii",
                "nr",
                "oc",
                "oj",
                "cu",
                "om",
                "or",
                "os",
                "pa",
                "pi",
                "fa",
                "pl",
                "ps",
                "pt",
                "qu",
                "rm",
                "rn",
                "ro",
                "ru",
                "sa",
                "sc",
                "sd",
                "se",
                "sm",
                "sg",
                "sr",
                "gd",
                "sn",
                "si",
                "sk",
                "sl",
                "so",
                "st",
                "es",
                "su",
                "sw",
                "ss",
                "sv",
                "ta",
                "te",
                "tg",
                "th",
                "ti",
                "bo",
                "tk",
                "tl",
                "tn",
                "to",
                "tr",
                "ts",
                "tt",
                "tw",
                "ty",
                "ug",
                "uk",
                "ur",
                "uz",
                "ve",
                "vi",
                "vo",
                "wa",
                "cy",
                "wo",
                "fy",
                "xh",
                "yi",
                "yo",
                "za"
              ],
              "default": "en"
            },
            "example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Boundaries containing the requested place.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoundaryFeatureCollection"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request."
          },
          "401": {
            "description": "Missing or invalid Geoapify API key."
          },
          "429": {
            "description": "Rate limit or quota exceeded."
          },
          "500": {
            "description": "Internal gateway error."
          }
        }
      }
    },
    "/boundaries/consists-of": {
      "get": {
        "tags": [
          "Boundaries"
        ],
        "operationId": "getBoundariesConsistsOf",
        "summary": "Find boundaries contained by a place",
        "description": "Returns boundaries contained by the provided place.",
        "parameters": [
          {
            "name": "apiKey",
            "in": "query",
            "required": true,
            "description": "Geoapify API key.",
            "schema": {
              "type": "string"
            },
            "example": "YOUR_API_KEY"
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Geoapify place identifier.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 2048
            }
          },
          {
            "name": "boundary",
            "in": "query",
            "required": false,
            "description": "Boundary type to return.",
            "schema": {
              "type": "string",
              "enum": [
                "administrative",
                "postal_code",
                "political",
                "low_emission_zone",
                "public_transport",
                "traditional",
                "timezone",
                "religious_administration",
                "religious",
                "place",
                "neighborhood",
                "region",
                "municipality",
                "barony",
                "town",
                "health",
                "historic",
                "historic:administrative"
              ],
              "default": "administrative"
            },
            "example": "postal_code"
          },
          {
            "name": "sublevel",
            "in": "query",
            "required": false,
            "description": "Nested boundary depth.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 1
            },
            "example": 2
          },
          {
            "name": "geometry",
            "in": "query",
            "required": false,
            "description": "Optional geometry output mode.",
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 50
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Result language as a supported two-letter language code.",
            "schema": {
              "type": "string",
              "enum": [
                "ab",
                "aa",
                "af",
                "ak",
                "sq",
                "am",
                "ar",
                "an",
                "hy",
                "as",
                "av",
                "ae",
                "ay",
                "az",
                "bm",
                "ba",
                "eu",
                "be",
                "bn",
                "bh",
                "bi",
                "bs",
                "br",
                "bg",
                "my",
                "ca",
                "ch",
                "ce",
                "ny",
                "zh",
                "cv",
                "kw",
                "co",
                "cr",
                "hr",
                "cs",
                "da",
                "dv",
                "nl",
                "en",
                "eo",
                "et",
                "ee",
                "fo",
                "fj",
                "fi",
                "fr",
                "ff",
                "gl",
                "ka",
                "de",
                "el",
                "gn",
                "gu",
                "ht",
                "ha",
                "he",
                "hz",
                "hi",
                "ho",
                "hu",
                "ia",
                "id",
                "ie",
                "ga",
                "ig",
                "ik",
                "io",
                "is",
                "it",
                "iu",
                "ja",
                "jv",
                "kl",
                "kn",
                "kr",
                "ks",
                "kk",
                "km",
                "ki",
                "rw",
                "ky",
                "kv",
                "kg",
                "ko",
                "ku",
                "kj",
                "la",
                "lb",
                "lg",
                "li",
                "ln",
                "lo",
                "lt",
                "lu",
                "lv",
                "gv",
                "mk",
                "mg",
                "ms",
                "ml",
                "mt",
                "mi",
                "mr",
                "mh",
                "mn",
                "na",
                "nv",
                "nb",
                "nd",
                "ne",
                "ng",
                "nn",
                "no",
                "ii",
                "nr",
                "oc",
                "oj",
                "cu",
                "om",
                "or",
                "os",
                "pa",
                "pi",
                "fa",
                "pl",
                "ps",
                "pt",
                "qu",
                "rm",
                "rn",
                "ro",
                "ru",
                "sa",
                "sc",
                "sd",
                "se",
                "sm",
                "sg",
                "sr",
                "gd",
                "sn",
                "si",
                "sk",
                "sl",
                "so",
                "st",
                "es",
                "su",
                "sw",
                "ss",
                "sv",
                "ta",
                "te",
                "tg",
                "th",
                "ti",
                "bo",
                "tk",
                "tl",
                "tn",
                "to",
                "tr",
                "ts",
                "tt",
                "tw",
                "ty",
                "ug",
                "uk",
                "ur",
                "uz",
                "ve",
                "vi",
                "vo",
                "wa",
                "cy",
                "wo",
                "fy",
                "xh",
                "yi",
                "yo",
                "za"
              ],
              "default": "en"
            },
            "example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Boundaries contained by the requested place.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoundaryFeatureCollection"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request."
          },
          "401": {
            "description": "Missing or invalid Geoapify API key."
          },
          "429": {
            "description": "Rate limit or quota exceeded."
          },
          "500": {
            "description": "Internal gateway error."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BoundaryFeatureCollection": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "features"
        ],
        "properties": {
          "type": {
            "const": "FeatureCollection"
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BoundaryFeature"
            }
          }
        }
      },
      "BoundaryFeature": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "properties",
          "geometry"
        ],
        "properties": {
          "type": {
            "const": "Feature"
          },
          "properties": {
            "$ref": "#/components/schemas/BoundaryProperties"
          },
          "geometry": {
            "$ref": "#/components/schemas/GeoJsonGeometry"
          },
          "bbox": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "number"
            }
          }
        }
      },
      "BoundaryProperties": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "place_id": {
            "type": "string",
            "description": "Geoapify place identifier."
          },
          "boundary": {
            "type": "string",
            "enum": [
              "administrative",
              "postal_code",
              "political",
              "low_emission_zone",
              "public_transport",
              "traditional",
              "timezone",
              "religious_administration",
              "religious",
              "place",
              "neighborhood",
              "region",
              "municipality",
              "barony",
              "town",
              "health",
              "historic",
              "historic:administrative"
            ]
          },
          "boundary_type": {
            "type": "string",
            "enum": [
              "administrative",
              "postal_code",
              "political",
              "low_emission_zone",
              "public_transport",
              "traditional",
              "timezone",
              "religious_administration",
              "religious",
              "place",
              "neighborhood",
              "region",
              "municipality",
              "barony",
              "town",
              "health",
              "historic",
              "historic:administrative"
            ]
          },
          "name": {
            "type": "string"
          },
          "country_code": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2
          },
          "datasource": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "GeoJsonGeometry": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/PointGeometry"
          },
          {
            "$ref": "#/components/schemas/LineStringGeometry"
          },
          {
            "$ref": "#/components/schemas/PolygonGeometry"
          },
          {
            "$ref": "#/components/schemas/MultiPointGeometry"
          },
          {
            "$ref": "#/components/schemas/MultiLineStringGeometry"
          },
          {
            "$ref": "#/components/schemas/MultiPolygonGeometry"
          }
        ]
      },
      "PointGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "Point"
          },
          "coordinates": {
            "$ref": "#/components/schemas/Position"
          }
        }
      },
      "LineStringGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "LineString"
          },
          "coordinates": {
            "type": "array",
            "minItems": 2,
            "items": {
              "$ref": "#/components/schemas/Position"
            }
          }
        }
      },
      "PolygonGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "Polygon"
          },
          "coordinates": {
            "type": "array",
            "items": {
              "type": "array",
              "minItems": 4,
              "items": {
                "$ref": "#/components/schemas/Position"
              }
            }
          }
        }
      },
      "MultiPointGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "MultiPoint"
          },
          "coordinates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Position"
            }
          }
        }
      },
      "MultiLineStringGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "MultiLineString"
          },
          "coordinates": {
            "type": "array",
            "items": {
              "type": "array",
              "minItems": 2,
              "items": {
                "$ref": "#/components/schemas/Position"
              }
            }
          }
        }
      },
      "MultiPolygonGeometry": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "coordinates"
        ],
        "properties": {
          "type": {
            "const": "MultiPolygon"
          },
          "coordinates": {
            "type": "array",
            "items": {
              "type": "array",
              "items": {
                "type": "array",
                "minItems": 4,
                "items": {
                  "$ref": "#/components/schemas/Position"
                }
              }
            }
          }
        }
      },
      "Position": {
        "type": "array",
        "minItems": 2,
        "maxItems": 3,
        "prefixItems": [
          {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          {
            "type": "number"
          }
        ],
        "items": false
      }
    }
  }
}