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
- Register on Geoapify MyProjects page
- Create a new project.
- Go to the API Keys section. One API key is generated automatically. You can generate multiple API keys per project if required.
- Optionally, you can protect the API key by listing allowed IP addresses, HTTP referrers, origins, and CORS.
- Choose "Boundaries API" and an API key to get an URL and programming code.
- 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 |