Reverse geocoding

Turn coordinates into a structured address.

geo.reverse Stable point

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/geo/reverse

{
    "type": "object",
    "properties": {
        "country": {
            "type": [
                "string",
                "null"
            ],
            "minLength": 2,
            "maxLength": 2
        },
        "language": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 8
        },
        "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
        },
        "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
        }
    },
    "additionalProperties": false,
    "required": [
        "lat",
        "lng"
    ]
}

Request example

{
    "lat": 45.4985,
    "lng": -73.5664
}

Response

What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.

POST /v1/geo/reverse

Response schema

{
    "description": "The address at a point.",
    "data": {
        "type": "object",
        "properties": {
            "matched": {
                "type": "boolean",
                "description": "Whether an address was found."
            },
            "reason": {
                "type": "string",
                "description": "Why nothing matched. Present only when `matched` is false."
            },
            "address": {
                "type": "object",
                "properties": {
                    "address_1": {
                        "type": "string",
                        "description": "Street address."
                    },
                    "address_2": {
                        "type": "string",
                        "description": "Unit, suite or floor; empty when none."
                    },
                    "city": {
                        "type": "string"
                    },
                    "province": {
                        "type": "string",
                        "description": "Province or state, as the provider names it."
                    },
                    "country": {
                        "type": "string",
                        "description": "Country code, as the provider returns it."
                    },
                    "postcode": {
                        "type": "string"
                    },
                    "full_address": {
                        "type": "string",
                        "description": "The whole address on one line."
                    },
                    "country_code": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The country as an ISO 3166-1 alpha-2 code, the form forward geocoding answers with. Null when the provider named no country that maps to a code."
                    },
                    "province_code": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The province or state as its short code (QC, ON, NY), the form forward geocoding answers with; upper-cased as given when the country has no list of codes. Null when the provider named none."
                    }
                }
            },
            "provider": {
                "type": "string",
                "description": "The provider that answered."
            }
        },
        "required": [
            "matched"
        ]
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "geo.reverse",
    "billing": {
        "unit": "point",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "matched": true,
        "address": {
            "address_1": "1000 Rue de La Gauchetière Ouest",
            "address_2": "",
            "city": "Montreal",
            "province": "Quebec",
            "country": "CAN",
            "postcode": "H3B 4W5",
            "full_address": "1000 Rue de La Gauchetière Ouest, Montreal, QC, Canada",
            "country_code": "CA",
            "province_code": "QC"
        },
        "provider": "internal"
    }
}

What it costs

One address or coordinate.

Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.

Errors it can return