Forward geocoding

Turn an address into coordinates through a per-country provider chain.

geo.forward 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/forward

{
    "type": "object",
    "properties": {
        "address1": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 255,
            "description": "Required unless one of city,postcode is supplied."
        },
        "address2": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 255
        },
        "city": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 120
        },
        "country": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 120
        },
        "postcode": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 32
        },
        "province": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 120
        }
    },
    "additionalProperties": false
}

Request example

{
    "address1": "1000 Rue De La Gauchetière O",
    "city": "Montreal",
    "province": "QC",
    "country": "CA",
    "postcode": "H3B 4W5"
}

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/forward

Response schema

{
    "description": "The location of one address. A miss answers 200 with `matched: false` and is billed like a hit.",
    "data": {
        "type": "object",
        "properties": {
            "matched": {
                "type": "boolean",
                "description": "Whether a location was found. A miss is not an error and is still billed."
            },
            "reason": {
                "type": "string",
                "description": "Why nothing matched. Present only when `matched` is false."
            },
            "location": {
                "type": "object",
                "properties": {
                    "lat": {
                        "type": "number",
                        "description": "Latitude, WGS84."
                    },
                    "lng": {
                        "type": "number",
                        "description": "Longitude, WGS84."
                    }
                },
                "required": [
                    "lat",
                    "lng"
                ]
            },
            "address": {
                "type": "object",
                "description": "The matched address as the provider parsed it. Only the parts the provider returned are present; may be empty.",
                "properties": {
                    "number": {
                        "type": "string",
                        "description": "House number."
                    },
                    "street": {
                        "type": "string",
                        "description": "Street name, normalized."
                    },
                    "city": {
                        "type": "string"
                    },
                    "province": {
                        "type": "string",
                        "description": "Province or state."
                    },
                    "country": {
                        "type": "string",
                        "description": "ISO 3166-1 alpha-2."
                    },
                    "postcode": {
                        "type": "string"
                    },
                    "unit": {
                        "type": "string",
                        "description": "Unit, suite or apartment."
                    }
                }
            },
            "confidence": {
                "type": [
                    "number",
                    "null"
                ],
                "description": "0-1, as the provider reports it; null when the provider gives none."
            },
            "provider": {
                "type": "string",
                "description": "The provider that answered (see GET /v1/geo/coverage)."
            }
        },
        "required": [
            "matched"
        ]
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "geo.forward",
    "billing": {
        "unit": "point",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "matched": true,
        "location": {
            "lat": 45.498174,
            "lng": -73.566218
        },
        "address": {
            "number": "1000",
            "street": "rue de la gauchetière o",
            "city": "Montreal",
            "province": "QC",
            "country": "CA",
            "postcode": "h3b 4w5"
        },
        "confidence": 1,
        "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