Developer

Best practices

Service version: 1
Last edit: 2024.11.19
TomTom Orbis Maps

Important notes:

When to use the Geocoding API?

Use the Geocoding API when you want to resolve complete addresses (for example, “109 Park Row, New York, United States”). The Geocoding API can also geocode partial addresses and those with typos. The Geocoding API is not designed to interact with real users when the input is given letter-by-letter.

If you want to resolve an address in the app in which input is provided by people usually letter-by-letter. Please use Fuzzy Search.

The Geocoding API is built for automated systems processing complete, unambiguous postal addresses, or those that are incomplete, not well formatted, or with typos.

Geocode is popular among following market segments: fleet, ride hailing, and food delivery.

  • Fleet & Logistics: These companies are users of this service. Just send a list of fully-written addresses to get all coordinates for route planning.
  • Fleet & Logistics, food delivery: It can be very useful for last mile, pick-up, drop-off, and delivery.
  • Ride hailing: for the pick-up and drop-off of passengers.
  • Data analysis:
    • Data from the Geocoding API can be used in spatial analysis when results are derived by computer processing.
    • It can be used for address verification to detect fraud.
  • Data transformation: Geocoding is an important component of data transformation because it can improve the data quality of a company's address database by cleaning and enhancing data.
  • User applications: Geocode can be also useful in user applications. For example, when trying to resolve address issues that are not human-to-machine interactions and the query contains a full address.

How to use request parameters to get better results?

The following topics provide some helpful tips to improve your Geocoding API query results.

Note: Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Using geo-biasing with a lat/lon pair

In order to geo-bias your results to the relevant area for your user, you should always use a lat/lon pair to help bias the results to the user's location. Note, this is a non-restrictive bias, but for very common searches it will find the instances nearby. This query will find places around the lat/lon:

Lat/lon pair
https://api.tomtom.com/maps/orbis/places/geocode/De Ruijterkade 154, 1011 AC, Amsterdam.json?lat=52.3773&lon=4.9084&key={Your_API_Key}

Using radius

If geo-biasing is not strong enough for keeping your results local to the user, you can also pass in a radius (in meters) to restrict the result to a given area. For instance, this query will only find an item within 1000 meters of the given lat/lon:

Radius
https://api.tomtom.com/maps/orbis/places/geocode/De Ruijterkade 154, 1011 AC, Amsterdam.json?lat=52.3773&lon=4.9084&radius=1000&key={Your_API_Key}

Using idxSet

You can also specify the exact set of indexes to query in the idxSet parameter. For instance if you are only interested:

idxSet
https://api.tomtom.com/maps/orbis/places/geocode/De Ruijterkade 154, 1011 AC, Amsterdam.json?lat=52.3773&lon=4.9084&idxSet=PAD,Str,Xstr,Geo,Addr&key={Your_API_Key}

The idxSet parameter value set of indexes that can be used are:

  • PAD = Point Addresses
  • Str = Streets
  • Geo = Geographies
  • Xstr = Cross Streets (intersections)
  • Addr = Address range interpolation (when there is no PAD)

Note: If you are using more than one index, do not include any spaces between them in the comma-separated string.

Using a subset of countries

You can also specify a subset of the countries on the server by adding a comma-separated list of countries in the form:

Subset of countries
https://api.tomtom.com/maps/orbis/places/geocode/De Ruijterkade 154, 1011 AC, Amsterdam.json?&countrySet=NL&key={Your_API_Key}

See the TomTom Geocoding API Market Coverage page for a list of all the countries supported by the Geocoding API engine.

Understanding a response

The following example uses JSON. Note: For your benefit, the code comments are preceded by // and are not part of the actual JSON.

JSON Response
1{
2	"summary": {
3		"query": "de ruijterkade 154 1011 ac amsterdam", //echo of the query
4		"queryType": "NON_NEAR",
5		"queryTime": 156, //query time on server in milliseconds
6		"numResults": 1, //total number of result in this response
7		"offset": 0, //if limit and offset are being used for paging
8		"totalResults": 1, //total number of hits within the entire database
9		"fuzzyLevel": 1 //range of 2-4 indicating depth of strategies used
10	},
11	"results": [
12		{
13			"type": "Point Address", //responses type (see table of types above)
14			"id": "NL/PAD/p0/3802262", //non-stable id for this document (might change in subsequent release)
15			"score": 13.2504415512,
16			"matchConfidence": {
17			"score": 1 //Represents overall textual match score, in the range of [0..1], where 1 means perfect match and 0 - no match.
18			},
19			"address": {
20				"streetNumber": "154",
21				"streetName": "De Ruijterkade",	//The street name.
22				"municipality": "Amsterdam", //City / Town
23				"countrySubdivision": "Noord-Holland",	//State or Province
24				"postalCode": "1011", //Postal Code / Zip Code
25				"extendedPostalCode": "1011 AC", //Extended postal code (availability dependent on region).
26				"countryCode": "NL", //A country's code (Note: This is a two-letter code, not a country name.).
27				"country": "Nederland", //Country name
28				"countryCodeISO3": "NLD" //ISO alpha-3 country code
29				"freeformAddress": "De Ruijterkade 154, 1011 AC Amsterdam", //An address line formatted according to the formatting rules of the result's country of origin. In the case of countries, its full country name. For the USA, in the case of geographies with entityType == PostalCodeArea it will contain the postalName field value.
30				"localName": "Amsterdam" //An address component which represents the name of a geographic area or locality that groups a number of addressable objects for addressing purposes, without being an administrative unit.
31			},
32			"position": {
33				"lat": 52.37727,
34				"lon": 4.90943
35			},
36			"viewport": {
37				"topLeftPoint": {
38					"lat": 52.37817,
39					"lon": 4.90796
40				},
41				"btmRightPoint": {
42					"lat": 52.37637,
43					"lon": 4.9109
44				}
45			},
46			"entryPoints": [
47				{
48					"type": "main",
49					"position": {
50						"lat": 52.37739,
51						"lon": 4.90944
52					}
53				}
54			]
55		}
56	]
57}