Geocoding (Search)

Match a query string to geographic coordinates.

Note: From now on autocomplete endpoint is the same as search endpoint.

Usage guidelines for autocomplete

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. Can be an address, a postcode or a venue. For example SW1A 0AA or Victoria street, London. Providing a country or city the request will get you more accurate results
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/search?query=Parliament square&focus.lat=51.512539&focus.lng=-0.097541 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": [
                    -0.126906,
                    51.500227
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, London, England, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "neighbourhood": "Westminster",
                "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.078529,
                    51.795574
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Hertford, England, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "region": "Hertfordshire",
                "region_code": "HRT",
                "macroregion": "England",
                "city": "Hertford",
                "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": [
                    -90.613019,
                    38.775132
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, St. Peters, MO, USA",
                "score": 1,
                "street": "Parliament Square",
                "region": "Missouri",
                "region_code": "MO",
                "county": "St. Charles County",
                "city": "St. Peters",
                "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": [
                    -4.386486,
                    54.321964
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Isle of Man",
                "score": 1,
                "street": "Parliament Square",
                "region": "Isle of Man",
                "country": "Isle of Man",
                "country_code": "IMN",
                "continent": "Europe",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": true,
                    "postcodes": true
                }
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -2.998166,
                    55.150669
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Langholm, Scotland, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "region": "Dumfries and Galloway",
                "region_code": "DGY",
                "macroregion": "Scotland",
                "city": "Langholm",
                "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": [
                    -3.190359,
                    55.949194
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Edinburgh, Scotland, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "region": "City of Edinburgh",
                "region_code": "EDH",
                "neighbourhood": "Old Town",
                "macroregion": "Scotland",
                "city": "Edinburgh",
                "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": [
                    -85.704736,
                    38.257593
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Louisville, KY, USA",
                "score": 1,
                "street": "Parliament Square",
                "region": "Kentucky",
                "region_code": "KY",
                "neighbourhood": "Frankfort Ave",
                "county": "Jefferson County",
                "city": "Louisville",
                "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": [
                    -3.421304,
                    56.203367
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Kinross, Scotland, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "region": "Perth and Kinross",
                "macroregion": "Scotland",
                "city": "Kinross",
                "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": [
                    -3.117136,
                    56.263332
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Scotland, United Kingdom",
                "score": 1,
                "street": "Parliament Square",
                "macroregion": "Scotland",
                "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": [
                    -83.703456,
                    41.663293
                ]
            },
            "properties": {
                "name": "Parliament Square",
                "label": "Parliament Square, Sylvania, OH, USA",
                "score": 1,
                "street": "Parliament Square",
                "region": "Ohio",
                "region_code": "OH",
                "county": "Lucas County",
                "country": "United States",
                "country_code": "USA",
                "continent": "North America",
                "features": {
                    "public_transport": {
                        "date_start": "",
                        "date_end": ""
                    },
                    "fares": false,
                    "postcodes": false
                }
            }
        }
    ]
}