Skip to content

Area Service

The area service provides a REST API for querying boundaries and areas based on geographic coordinates or OpenStreetMap IDs. The API supports JSON and GeoJSON formats.

Levels

The table shows the typical usage of admin_level values in OpenStreetMap for different administrative levels. However, the exact meaning may vary depending on the country and region. Values 2 to 11 are most commonly used, but some countries may define additional levels. You can check the country-specific meanings of the admin_level values in this table.

Level Description
0 Unique SmartMaps-Level for ZIP-Codes
2 National borders
3 States, provinces, regions (1st level)
4 Counties, districts, regions (2nd level)
5 Municipalities, cities, metropolitan regions
6 Townships, boroughs, city districts, sub-municipalities
7 Neighborhoods, quarters, villages, hamlets
8 City blocks, wards, subdivisions, localities, settlements
9 Statistical districts, zip code areas, electoral districts
10 Blocks, quarters, neighborhoods, census districts
11 Electoral wards, school districts, parishes, census districts

Endpoints

Get Boundaries at a Point

Retrieves the boundaries and areas at a specific geographic point.

POST https://area.smartmaps.cloud/api/v2/Boundaries/point

GET  https://area.smartmaps.cloud/api/v2/Boundaries/point

Parameters:

Parameter Required Type Description
apiKey Yes string API key for authentication
channel No string Channel for the request
level Yes integer Administrative level of the boundaries (e.g., 2 for countries)
latitude Yes number Latitude of the point
longitude Yes number Longitude of the point
isoCountries No string Comma-separated list of ISO country codes for filtering
isoLanguages No string Comma-separated list of ISO language codes for the results
reduceGeometry No number Factor for reducing the accuracy of the geometries (0-1)
zoom No integer Zoom level to determine the level of detail for the geometries

The request body must be a JSON object with a points array containing the points to query.

POST Request body example

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "level": 0,
  "points": [
    {
      "latitude": 0,
      "longitude": 0
    }
  ]
}

Response:

The response is a GeoJSON FeatureCollection containing the boundaries and areas at the specified points.

Get Boundaries in a Rectangle

Retrieves the boundaries and areas within a rectangular extent.

POST https://area.smartmaps.cloud/api/v2/Boundaries/rectangle

GET https://area.smartmaps.cloud/api/v2/Boundaries/rectangle

Parameters:

Parameter Required Type Description
apiKey Yes string API key for authentication
channel No string Channel for the request
level Yes integer Administrative level of the boundaries
isoCountries No string Comma-separated list of ISO country codes for filtering
isoLanguages No string Comma-separated list of ISO language codes for the results
reduceGeometry No number Factor for reducing the accuracy of the geometries (0-1)
zoom No integer Zoom level to determine the level of detail for the geometries

The request body must be a JSON object with a boundingBox property containing the coordinates of the rectangle.

POST Request body example

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "level": 0,
  "boundingBox": {
    "northEast": {
      "latitude": 0,
      "longitude": 0
    },
    "southWest": {
      "latitude": 0,
      "longitude": 0
    }
  }
}

Response:

The response is a GeoJSON FeatureCollection containing the boundaries within the specified rectangle.

Get Boundaries for an OSM ID

Retrieves the boundaries and areas for an OpenStreetMap ID.

POST https://area.smartmaps.cloud/api/v2/Boundaries/osmid

Parameters:

Parameter Required Type Description
apiKey Yes string API key for authentication
channel No string Channel for the request
osmid Yes integer OpenStreetMap ID
isoCountries No string Comma-separated list of ISO country codes for filtering
isoLanguages No string Comma-separated list of ISO language codes for the results
reduceGeometry No number Factor for reducing the accuracy of the geometries (0-1)
zoom No integer Zoom level to determine the level of detail for the geometries
latitude No number Latitude for the center of the geometries

POST Request body example

{
  "isoCountries": [
    "string"
  ],
  "reduceGeometry": 0,
  "isoLanguages": [
    "string"
  ],
  "zoom": 0,
  "osmids": [
    0
  ],
  "latitude": 0
}

Response:

The response is a GeoJSON FeatureCollection containing the boundaries for the specified OSM ID.

Data Model

The API responses contain GeoJSON FeatureCollections with the following properties:

  • type: Type of the GeoJSON object ("FeatureCollection")
  • bbox: Bounding box of the boundaries
  • features: Array containing the individual boundaries and areas
  • type: Type of the feature ("Feature")
  • geometry: Geometry of the boundary as a GeoJSON object
  • properties: Additional properties such as names and codes of the boundary

For each boundary, the names in different languages, the ISO code of the associated country, and a postal code are returned if available.

Swagger

For more detailed information on the response structures please refer to the full Swagger documentation.