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
-
string
-
stringRequired authentication header.For example:
X-Api-Key: rwyEPevhh54EqVqSyv7ovoDqYYYR5Z
-
BCP47 | optionalRequest 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
orAccept-Language: fr-FR
Request GET parameters
-
stringA query to geocode. Can be an address, a postcode or a venue. For example
SW1A 0AA
orVictoria street, London
. Providing a country or city the request will get you more accurate results -
ISO 3166-1 alpha-2 or alpha-3 | optionalOnly return the results that are within the specified country. If no results are found it will return the country itself.
-
experimental| string | optionalExclude 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 withwithin.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
-
BCP47Language 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 inGeoJSON
format (check example below). Note that coordinates
elements are longitude, latitude, in that order.
The properties
object contains the following attributes:
-
stringA short description of the location, varies depending on what is returned
-
stringDetailed label of the result, intended to be returned to the end user
-
float | optionalResult 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 | optionalTravel 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
-
object | optionalPublic transport support information. Public transport is not supported if this object is missing.
-
date in extended ISO-8601 format
-
date in extended ISO-8601 format
-
-
object | optionalFast 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.
-
stringThe 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.
-
stringPossible values
arrival.many_to_one
,arrival.one_to_many
. -
stringPossible values
public_transport
,driving
,driving+public_transport
.
-
-
-
-
booleanIndicates whether or not we have fare data
-
booleanIndicates 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
}
}
}
]
}