Boundaries API

The Boundaries API works via HTTP GET requests and returns the boundaries that a location is part of, or the boundaries that a location consists of. The API contains 2 API end-points:

part-of endpoint

Returns the list of boundaries the specified location belongs to.

https://api.geoapify.com/v1/boundaries/part-of?lon=12.789931425885811&lat=51.16772168907602&geometry=geometry_1000&apiKey=YOUR_API_KEY

  • lon, lat - location coordinates (or id, a place id, instead)
  • geometry - geometry type with specified accuracy
  • apiKey - your Geoapify key

consists-of endpoint

Returns the list of boundaries that are a part of the specified location.

https://api.geoapify.com/v1/boundaries/consists-of?id=519696318009c02840596da7e3bdc1ab4940f00101f901b9f4000000000000&geometry=geometry_1000&apiKey=YOUR_API_KEY

  • id - place id returned by Geocoding or Places API
  • geometry - geometry type with specified accuracy
  • apiKey - your Geoapify key

Note the parameter names for the boundary type: part-of takes boundaries (plural, one or more comma-separated types), consists-of takes boundary (singular, one type).

The response returned contains a GeoJSON FeatureCollection object with features of specified geometry type. Each Feature represents a separate boundary and has a Place Feature Specification.

Learn more

Authentication and API key

To use the API, you'll need an API key. But don't worry! You can register and get a Boundaries API key for free without a credit card. Our free plan includes 3,000 credits/day; see Pricing for how Boundaries API requests are counted. For more information on our plans, visit the Pricing page.

How to get Boundaries API key

  1. Register on Geoapify MyProjects page
  2. Create a new project.
  3. Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
  4. Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
  5. Choose "Boundaries API" and an API key to get an URL and programming code.
  6. Press the "Try" button to execute the API call and get the result object.

API Reference: Part Of

The API returns boundaries that the specified place is a part of. For example, city, county, state, and country for a location. The API can take as input place id or place coordinates. The API is implemented via HTTP Get request.

API URL

https://api.geoapify.com/v1/boundaries/part-of?PARAMS

Request parameters

Name Description
apiKey Geoapify API key
id Place id returned by the Geocoding API or the Places API. Skip lat, lon parameters when id specified
lat, lon Location coordinates. Skip id parameter when lat, lon specified
osm_id, osm_type OpenStreetMap object id and type (n for node, w for way, r for relation), for example osm_id=62428&osm_type=r. Alternative to id and lat, lon
boundaries Boundary types, comma-separated, for example boundaries=administrative,postal_code. Can take values: 'administrative', 'postal_code', 'political', 'low_emission_zone'. Default value is 'administrative'
geometry Boundary geometry type: a center point or a polygon with different accuracy. Can take values: 'point', 'geometry_1000', 'geometry_5000', 'geometry_10000'. Default value is 'point'
lang Result language. 2-character ISO 639-1 language codes are supported. Default value is 'en'

API Reference: Consists Of

The API returns boundaries that the specified place consists of. For example, states for a country or districts for a city. The API is implemented via HTTP Get request.

API URL

https://api.geoapify.com/v1/boundaries/consists-of?PARAMS

Request parameters

Name Description
apiKey Geoapify API key
id Required. Place id returned by the Geocoding API, the Places API, or the part-of endpoint
boundary One boundary type. Default value is 'administrative'. The main values are 'administrative', 'postal_code', 'political' and 'low_emission_zone'; the API also accepts 'public_transport', 'traditional', 'timezone', 'religious_administration', 'religious', 'place', 'neighborhood', 'region', 'municipality', 'barony', 'town', 'health', 'historic' and 'historic:administrative'. The result depends on the boundaries mapped in OpenStreetMap for the area
sublevel Nested subdivision depth, from 1 to 20. Default value is 1: the direct subdivisions of the place. Higher values return smaller subdivisions; for example, Bavaria (Germany) returns its 7 administrative regions with sublevel=1 and its 96 districts with sublevel=2
geometry Boundary geometry type: a center point or a polygon with different accuracy. Can take values: 'point', 'geometry_1000', 'geometry_5000', 'geometry_10000'. Default value is 'point'
lang Result language. 2-character ISO 639-1 language codes are supported. Default value is 'en'

Geometry types

Value Description
point Center point of a boundary
geometry_1000 'Polygon/Multipolygon' geometry with 1000m accuracy
geometry_5000 'Polygon/Multipolygon' geometry with 5000m accuracy
geometry_10000 'Polygon/Multipolygon' geometry with 10000m accuracy

Note! When you request boundaries for a big area with high accuracy the processing time and response size can take significant values.
Note! Each 'Polygon/Multipolygon' geometry returned by the API costs an additional credit.

API Reference: outputs

The response contains a GeoJSON FeatureCollection object containing features of "Point" or "Polygon/Multipolygon" types. Check the Feature specification for detailed information about Feature object properties.

Name Description
name Location name
country Country component of an address
state State component of an address
postcode Postcode or ZIP code of an address
city City component of an address
street Street component of an address
housenumber House number component of an address
lat, lon Coordinates of the location
formatted Display address
address_line1 Main part of the display address, contains building street and house number or amenity name
address_line2 The second part of the display address, contains address parts not included to address_line1
place_id Place id of the boundary. Use it as id in the consists-of endpoint, for example to get the subdivisions of a boundary returned by part-of
categories Boundary categories, for example administrative and administrative.county_level
datasource Data source and license. For OpenStreetMap boundaries, datasource.raw contains the original OpenStreetMap tags, including osm_id, osm_type and admin_level

Pricing

We offer several Pricing Plans, each with a different usage level in credits. Credits allow us to estimate an API call's price considering computing difficulty. You get 3,000 credits/day in the Free Pricing plan. You can upgrade your plan at any time if your usage goes over.

Here are some rules for calculating Boundaries API pricing:

Rule Cost in credits Example
Boundaries API Every 20 boundaries returned cost 1 credit 30 boundaries with Point geometry returned as a result cost 2 credits
Boundaries API + geometry Each geometry different than Point returned by Boundaries API is counted as 1 additional credit 30 boundaries with geometry_1000 parameter are counted as 2 credits + 30 credits = 32 credits
Learn more