Address autocomplete (beta)

Suggest addresses while they are typed, then give the chosen one as a structured address with coordinates.

geo.autocomplete Beta call

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

{
    "type": "object",
    "properties": {
        "countries": {
            "type": "array",
            "maxItems": 5,
            "items": {
                "type": "string",
                "minLength": 2,
                "maxLength": 2
            }
        },
        "input": {
            "type": "string",
            "minLength": 3,
            "maxLength": 200
        },
        "language": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 16
        },
        "near": {
            "type": [
                "object",
                "null"
            ],
            "properties": {
                "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Required when near is present."
                },
                "lng": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Required when near is present."
                },
                "radius_meters": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 1,
                    "maximum": 50000
                }
            }
        },
        "session_token": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 64
        },
        "types": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "address",
                "geocode",
                "establishment"
            ]
        }
    },
    "additionalProperties": false,
    "required": [
        "input"
    ]
}

Request example

{
    "input": "1000 rue de la Gauchetiere",
    "countries": [
        "ca"
    ],
    "session_token": "6f1c2a8e-4b1d-4a39-9d0e-5b8f3c7a21de"
}

POST /v1/geo/place

{
    "type": "object",
    "properties": {
        "language": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 16
        },
        "place_id": {
            "type": "string",
            "maxLength": 512
        },
        "session_token": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 64
        }
    },
    "additionalProperties": false,
    "required": [
        "place_id"
    ]
}

Request example

{
    "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww",
    "session_token": "6f1c2a8e-4b1d-4a39-9d0e-5b8f3c7a21de"
}

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

Response schema

{
    "description": "The suggestions for the text typed so far. Billed one call.",
    "data": {
        "type": "object",
        "properties": {
            "suggestions": {
                "type": "array",
                "description": "Up to five suggestions, best first.",
                "items": {
                    "type": "object",
                    "properties": {
                        "place_id": {
                            "type": "string",
                            "description": "Pass to POST /v1/geo/place for the address and coordinates."
                        },
                        "description": {
                            "type": "string",
                            "description": "The whole suggestion on one line."
                        },
                        "main_text": {
                            "type": "string",
                            "description": "The street part."
                        },
                        "secondary_text": {
                            "type": "string",
                            "description": "The city, province and country part."
                        },
                        "types": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            },
                            "description": "What the suggestion is (address, premise, subpremise, route ...)."
                        }
                    }
                }
            }
        },
        "required": [
            "suggestions"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "geo.autocomplete",
    "billing": {
        "unit": "call",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "suggestions": [
            {
                "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww",
                "description": "1000 Rue De la Gauchetière Ouest, Montreal, QC, Canada",
                "main_text": "1000 Rue De la Gauchetière Ouest",
                "secondary_text": "Montreal, QC, Canada",
                "types": [
                    "geocode",
                    "subpremise"
                ]
            },
            {
                "place_id": "ChIJybX38KwbyUwRuUlJnrlZOAk",
                "description": "1000 Rue de la Gauchetière Est, Montreal, QC, Canada",
                "main_text": "1000 Rue de la Gauchetière Est",
                "secondary_text": "Montreal, QC, Canada",
                "types": [
                    "geocode",
                    "subpremise"
                ]
            },
            {
                "place_id": "ChIJq6qqH10ayUwRDKm5QlrmM2g",
                "description": "1000 Rue de la Gauchetière E, Montreal, QC, Canada",
                "main_text": "1000 Rue de la Gauchetière E",
                "secondary_text": "Montreal, QC, Canada",
                "types": [
                    "geocode",
                    "subpremise"
                ]
            },
            {
                "place_id": "EjExMDAwIFJ1ZSBkZSBsYSBHYXVjaGV0acOocmUsIE1vbnRyZWFsLCBRQywgQ2FuYWRhIjESLwoUChIJGz5nxFwayUwRxfGQnpCySKkQ6AcqFAoSCZVv0iVdGslMEUpWKOwLwBz0",
                "description": "1000 Rue de la Gauchetière, Montreal, QC, Canada",
                "main_text": "1000 Rue de la Gauchetière",
                "secondary_text": "Montreal, QC, Canada",
                "types": [
                    "geocode",
                    "street_address"
                ]
            },
            {
                "place_id": "EjYxMDAwIFJ1ZSBkZSBsYSBHYXVjaGV0acOocmUsIE1vbnRyw6lhbC1Fc3QsIFFDLCBDYW5hZGEiLiosChQKEgk5hd5QFeLITBFVgO8QJcFsCBIUChIJndvyLgHiyEwREdLOpOC4H6k",
                "description": "1000 Rue de la Gauchetière, Montréal-Est, QC, Canada",
                "main_text": "1000 Rue de la Gauchetière",
                "secondary_text": "Montréal-Est, QC, Canada",
                "types": [
                    "geocode",
                    "route"
                ]
            }
        ]
    },
    "meta": {
        "provider": "google"
    }
}

POST /v1/geo/place

Response schema

{
    "description": "The suggestion's address and coordinates. Billed one call.",
    "data": {
        "type": "object",
        "properties": {
            "place_id": {
                "type": "string",
                "description": "The place id."
            },
            "formatted_address": {
                "type": "string",
                "description": "The address on one line."
            },
            "address": {
                "type": "object",
                "properties": {
                    "number": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Civic number."
                    },
                    "street": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Street name."
                    },
                    "address_1": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Number and street."
                    },
                    "address_2": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Unit or suite, when the place has one."
                    },
                    "city": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "City."
                    },
                    "province": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Province or state code."
                    },
                    "country": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "ISO 3166-1 alpha-2 country code."
                    },
                    "postcode": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Postcode."
                    }
                }
            },
            "location": {
                "type": [
                    "object",
                    "null"
                ],
                "description": "The coordinates, `{lat, lng}`."
            }
        },
        "required": [
            "place_id",
            "address",
            "location"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {},
        "additionalProperties": true
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "geo.autocomplete",
    "billing": {
        "unit": "call",
        "quantity": 1,
        "counted": true
    },
    "data": {
        "place_id": "ChIJWeWFxFwayUwRgP5QVJUn5ww",
        "formatted_address": "1000 Rue De la Gauchetière O, Montréal, QC H3B 4W5, Canada",
        "address": {
            "number": "1000",
            "street": "Rue De la Gauchetière Ouest",
            "address_1": "1000 Rue De la Gauchetière Ouest",
            "address_2": null,
            "city": "Montréal",
            "province": "QC",
            "country": "CA",
            "postcode": "H3B 4W5"
        },
        "location": {
            "lat": 45.4981354,
            "lng": -73.5659122
        }
    },
    "meta": {
        "provider": "google"
    }
}

What it costs

One call, whatever its size.

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

Errors it can return