Geocoding (Autocomplete)

Match a query string to geographic coordinates. This endpoint is designed to be used in location input with type-ahead support.

The difference from Geocoding [Search] is that this endpoint uses a different query parser, which takes into account that the user is typing and query may not be complete.

Usage guidelines

Fast typers may send a lot of requests at once and their device/network may not perform well with many open connections. Because of this, some kind of client-side request throttling must be implemented.

Furthermore, requests are asynchronous and you must account for the fact that responses may not be received in the same order they were requested.

Request Headers

X-Application-Id

string

Required authentication header. Get API Key here

For example:
X-Application-Id: fa12pA96
X-Api-Key

string

Required authentication header.
For example:
X-Api-Key: rwyEPevhh54EqVqSyv7ovoDqYYYR5Z
Accept-Language

BCP47 | optional

Request geocoding results to be in specific language if it is available. If it is not - it will default to English. BCP47 spec.
For example:

Accept-Language: en or Accept-Language: fr-FR

Request GET parameters

query

string

A query to geocode. Set this parameter to whatever the user has typed in the type-ahead input. Must be at least 2 characters long
focus.lat | focus.lng

float | optional

Latitude and longitude of a focus point. This will prioritize results around this point. Note that this does not exclude results that are far away from the focus point
within.country

ISO 3166-1 alpha-2 or alpha-3 | optional

Only return the results that are within the specified country. If no results are found it will return the country itself.
exclude.location.types

experimental
| string | optional

Exclude location types from results. Available values: country.

Example #1: exclude.location.types=country.

Example #2: This parameter can be used to exclude countries from the results after filtering down with within.country parameter.

search?query=Namibia&within.country=CH&exclude.location.types=country will return empty result set, because Switzerland itself will be excluded.

Response Headers

Content-Language

BCP47

Language tag in which results were returned.

It will default to Content-Language: en if requested language was not available. BCP47 spec

Response Body Json Attributes

The returned response is in GeoJSON format (check example below). Note that coordinates elements are longitude, latitude, in that order. The properties object contains the following attributes:

name

string

A short description of the location, varies depending on what is returned
label

string

Detailed label of the result, intended to be returned to the end user
score

float | optional

Result confidence score, maximum value is 1
house_number

string | optional
street

string | optional
region

string | optional
region_code

string | optional
neighbourhood

string | optional
county

string | optional
macroregion

string | optional
city

string | optional
country

string | optional
country_code

ISO 3166-1 alpha-3 | optional
continent

string | optional
postcode

string | optional
features

object | optional

Travel Time features that are supported for searches from this point. If the object is missing, it means that Travel Time searches from this point are not supported
Show/Hide Child Attributes
- public_transport
  
  object | optional
  
  Public transport support information. Public transport is not supported if this object is missing.
  Show/Hide Child Attributes
  - date_start
    
    date in extended ISO-8601 format
  - date_end
    
    date in extended ISO-8601 format
- time_filter_fast
  
  object | optional
  
  Fast time-filter support information. The time-filter/fast endpoint is not supported if this object is missing.
  Show/Hide Child Attributes
  - periods
    
    array[object]
    
    Each entry in the array describes a time period and time filter modes that are available for this country.
    
    Show/Hide Child Attributes
    
    time_period
    
    string
    
    The arrival or departure time period for which this time filter fast endpoint is available. Possible values: weekday_morning
    
    supported
    
    array[object]
    
    Lists available transportation and time-filter modes for this time period.
    
    Show/Hide Child Attributes
    
    search_type
    
    string
    
    Possible values arrival.many_to_one, arrival.one_to_many.
    
    transportation_mode
    
    string
    
    Possible values public_transport, driving, driving+public_transport.
- fares
  
  boolean
  
  Indicates whether or not we have fare data
- postcode
  
  boolean
  
  Indicates whether or not postcode searches are supported

Example Request

GET /v4/geocoding/autocomplete?query=lon HTTP/1.1
Host: api.traveltimeapp.com
Accept: application/json
X-Application-Id: ...
X-Api-Key: ...

Response Body

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    10.99153,
                    46.08536
                ]
            },
            "properties": {
                "name": "Lon",
                "label": "Lon, Italy",
                "region": "Trento",
                "region_code": "TN",
                "macroregion": "Trentino-Alto Adige/South Tyrol",
                "city": "Lon",
                "country": "Italy",
                "country_code": "ITA",
                "continent": "Europe",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": false,
                    "postcodes": false
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -93.05935,
                    37.18366
                ]
            },
            "properties": {
                "name": "Lon",
                "label": "Lon, MO, USA",
                "region": "Missouri",
                "region_code": "MO",
                "county": "Webster County",
                "city": "Lon",
                "country": "United States",
                "country_code": "USA",
                "continent": "North America",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": false,
                    "postcodes": false
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.099076,
                    51.509648
                ]
            },
            "properties": {
                "name": "London",
                "label": "London, England, United Kingdom",
                "macroregion": "England",
                "city": "London",
                "country": "United Kingdom",
                "country_code": "GBR",
                "continent": "Europe",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": true,
                    "postcodes": true
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.30864,
                    51.49227
                ]
            },
            "properties": {
                "name": "London",
                "label": "London, England, United Kingdom",
                "neighbourhood": "Northfields",
                "macroregion": "England",
                "city": "London",
                "country": "United Kingdom",
                "country_code": "GBR",
                "continent": "Europe",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": true,
                    "postcodes": true
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    116.740142,
                    25.266203
                ]
            },
            "properties": {
                "name": "Longyan",
                "label": "Longyan, China",
                "region": "Fujian",
                "county": "Longyan",
                "country": "China",
                "country_code": "CHN",
                "continent": "Asia"
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    105.200776,
                    33.637824
                ]
            },
            "properties": {
                "name": "Longnan",
                "label": "Longnan, China",
                "region": "Gansu",
                "county": "Longnan",
                "country": "China",
                "country_code": "CHN",
                "continent": "Asia"
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.16667,
                    51.5
                ]
            },
            "properties": {
                "name": "Greater London",
                "label": "Greater London, England, United Kingdom",
                "macroregion": "England",
                "country": "United Kingdom",
                "country_code": "GBR",
                "continent": "Europe",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": true,
                    "postcodes": true
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -73.06622,
                    40.81677
                ]
            },
            "properties": {
                "name": "Long Island",
                "label": "Long Island, Holtsville, NY, USA",
                "region": "New York",
                "region_code": "NY",
                "county": "Suffolk County",
                "city": "Holtsville",
                "country": "United States",
                "country_code": "USA",
                "continent": "North America",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": false,
                    "postcodes": false
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -97.694567,
                    31.11042
                ]
            },
            "properties": {
                "name": "Lone Star",
                "label": "Lone Star, Killeen, TX, USA",
                "region": "Texas",
                "region_code": "TX",
                "neighbourhood": "Lone Star",
                "county": "Bell County",
                "city": "Killeen",
                "country": "United States",
                "country_code": "USA",
                "continent": "North America",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": false,
                    "postcodes": false
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    77.1807,
                    30.89928
                ]
            },
            "properties": {
                "name": "Lon",
                "label": "Lon, India",
                "region": "Himachal Pradesh",
                "region_code": "HP",
                "county": "Solan",
                "city": "Lon",
                "country": "India",
                "country_code": "IND",
                "continent": "Asia"
            }
        }
    ]
}