Boundaries API

The Boundaries API works via HTTP Get request and allows to get boundaries that the specified location is part of or that the specified 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 ccordinates
  • 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

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.

Authenfication 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 up to 3000 requests/day. 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 Geometry API or Places API. Skip lat, lon parameters when id specified
lat, lon Location coordinates. Skip id parameter when lat, lon specified
boundary Boundary type. Can take values: 'administrative', 'postal_code', 'political', 'low_emission_zone'. Default value is 'administrative'
geometry Boundary geometry type. Lets to get geometry 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

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


Request parameters

Name Description
apiKey Geoapify API key
id place id returned by Geometry API or Places API
boundary Boundary type. Can take values: 'administrative', 'postal_code', 'political', 'low_emission_zone'. Default value is 'administrative'
sublevel Relative subdivisions level. Lets to get smaller subdivisions - for example, neighborhoods instead of districts
geometry Boundary geometry type. Lets to get geometry 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

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

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