Skip to content

Geocoding

The geocoding API provides a way to convert location data into a human-readable data.

Using a pair of coordinates

Perform a reverse geocoding request to convert a longitude and latitude pair into a human-readable address.

POST /maps/geocoder/v1/reverse-geocode
[ -0.143114, 51.538792 ]

Tip

The coordinates are represented as an array with the longitude and latitude values.

Optional arguments:

  • types: A list of data types to return, separated by commas. Possible values are addr, road, postcode, boundary and all. Defaults to addr.
  • includeGeometry: Whether to include geometry information in the response. Defaults to false.
  • tolerance: The maximum distance in meters from the input coordinates. Defaults to 100.
  • language: A two-letter language code (ISO 639-1) to use for the response (eg. en). If not specified, all languages are returned.

Note

Particularly for boundary data types, it is recommended to always specify the language parameter. Not doing so may result in larger responses, as all available languages for the requested data types will be returned.

Response:

{
    "data": [
        {
            "type": "address",
            "context": {},
            "properties": {
                "city": "London",
                "name": "Portico",
                "street": "Parkway",
                "postcode": "NW1 7PG",
                "housenumber": "3"
            }
        },
        {
            "type": "road",
            "context": {},
            "properties": {
                "lit": "yes",
                "ref": "A4201",
                "name": "Parkway",
                "lanes": "2",
                "oneway": "yes",
                "highway": "primary",
                "surface": "asphalt",
                "cycleway": "no",
                "maxspeed": "20 mph",
                "sidewalk": "both",
                "turn:lanes:forward": "left;slight_left|through",
                "maxspeed:computed": "32.19"
            }
        },
        {
            "type": "postcode",
            "context": {},
            "properties": {
                "name": "NW1",
                "addr:city": "London",
                "addr:country": "United Kingdom",
                "addr:country_code": "GB"
            }
        },
        {
            "type": "boundary",
            "context": {},
            "properties": {
                "name": "Camden",
                "admin_level": "9",
                "boundary": "administrative",
                "addr:city": "London",
                "addr:country": "United Kingdom",
                "addr:country_code": "GB"
            }
        }
    ]
}

Note

For the road data type, the maxspeed:computed property is calculated based on other maxspeed values. The value is in kilometers per hour.

Using a bounding box

Perform a reverse geocoding request to convert a bounding box area into human-readable addresses. The bounding box area must not exceed 100.000.000 m2.

POST /maps/geocoder/v1/bbox/reverse-geocode
[ -1.100048, 50.791111, -1.085836, 50.800095 ]

Tip

The bounding box is represented as an array with the west, south, east and north values.

Optional arguments:

  • types: A list of data types to return, separated by commas. Possible values are road, postcode, boundary and all. Defaults to boundary.

  • includeGeometry: Whether to include geometry information in the response. Defaults to false.

  • language: A two-letter language code (ISO 639-1) to use for the response (eg. en). If not specified, all languages are returned.

Response:

{
    "context": {
        "bbox": [
        -1.100048,
        50.791111,
        -1.085836,
        50.800095
    ]
    },
    "data": [
        {
            "type": "boundary",
            "context": {},
            "properties": {
                "name": "Camden",
                "admin_level": "9",
                "boundary": "administrative",
                "addr:city": "London",
                "addr:country": "United Kingdom",
                "addr:country_code": "GB"
            }
        },
        // ...
    ]
}

Warning

When requesting road data, the bounding box size can't exceed 1.000.000 m2.