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 his 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

  • Required authentication header. Get API Key here
    For example:
    X-Application-Id: fa12pA96
  • Required authentication header.
    For example:
    X-Application-Key: rwyEPevhh54EqVqSyv7ovoDqYYYR5Z
  • 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

  • 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
  • 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
  • ISO 3166-1 alpha-2 or alpha-3 | optional
    Only return the results that are within the specified country

Response Headers

  • 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:
  • string
    A short description of the location, varies depending on what is returned
  • string
    Detailed label of the result, intended to be returned to the end user
  • float | optional
    Result confidence score, maximum value is 1
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • string | optional
  • ISO 3166-1 alpha-3 | optional
  • string | optional
  • string | optional
  • object | optional
    Travel Time Platform features that are supported for searches from this point. If the object is missing, it means that Travel Time Platform searches from this point are not supported
    • object | optional
      Public transport support information. Public transport is not supported if this object is missing.
    • object | optional
      Fast time-filter support information. The time-filter/fast endpoint is not supported if this object is missing.
      • array[object]
        Each entry in the array describes a time period and time filter modes that are available for this country.
        • string
          The arrival or departure time period for which this time filter fast endpoint is available. Possible values: weekday_morning
        • array[object]
          Lists available transportation and time-filter modes for this time period.
          • string
            Possible values arrival.many_to_one, arrival.one_to_many.
          • Possible values public_transport, driving, driving+public_transport.
    • boolean
      Indicates whether or not we have fare data
    • 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": "2018-02-15T01:00:00+02:00",
                        "date_end": "2018-04-20T01:00:00+03:00"
                    },
                    "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": "2018-03-06T08:00:00+02:00",
                        "date_end": "2018-05-09T08:00:00+03:00"
                    },
                    "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": "2018-02-27T02:00:00+02:00",
                        "date_end": "2018-05-02T02:00:00+03:00"
                    },
                    "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": "2018-02-27T02:00:00+02:00",
                        "date_end": "2018-05-02T02:00:00+03:00"
                    },
                    "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": "2018-02-27T02:00:00+02:00",
                        "date_end": "2018-05-02T02:00:00+03:00"
                    },
                    "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": "2018-03-02T07:00:00+02:00",
                        "date_end": "2018-05-05T07:00:00+03:00"
                    },
                    "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": "2018-03-01T08:00:00+02:00",
                        "date_end": "2018-05-04T08:00:00+03:00"
                    },
                    "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"
            }
        }
    ]
}