Best practices

Service version: 2 Last edit: 2024.07.18

Important note This Premium Geocoding API is unavailable on a Freemium or Pay As You Grow (PAYG) basis. Click the Request Access button above to contact our Sales team.

When to use the Premium Geocoding API?

The TomTom Premium Geocoding API is a forward geocoding service that returns highly accurate address coordinates along with expanded address features required for last-mile delivery, such as the closest parking points, floor numbering, and building entrances (data not provided by standard geocoding). This enables, for example, address verification, route planning, and to-the-door navigation. Premium geocoding therefore guides couriers to the customer’s door for faster and more successful deliveries, compared to the standard geocoded location available in regular geocoding.

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

It can especially be used at multi-family apartment buildings that require more than just an address placed on the street.

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

How to use request parameters to get better results?

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

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

Using unit for detailed addresses

In order to search detailed unit level address you should use the unit parameter. The unit details can also be within the query itself but for better accuracy use the unit parameter separately.

unit

1
https://api.tomtom.com/search/2/premiumGeocode/3401 S Lamar Blvd, Austin, TX.json?unit=apt 3441&key={Your_API_Key}

unit embedded in query

1
https://api.tomtom.com/search/2/premiumGeocode/3401 S Lamar Blvd, apt 3441, Austin, TX.json?key={Your_API_Key}

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

1
https://api.tomtom.com/search/2/premiumGeocode/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

1
https://api.tomtom.com/search/2/premiumGeocode/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

1
https://api.tomtom.com/search/2/premiumGeocode/3401 S Lamar Blvd, Austin, TX.json?lat=52.3773&lon=4.9084&idxSet=PAD,Str,Xstr,Geo,Addr&key={Your_API_Key}&unit=apt 3441

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

1
https://api.tomtom.com/search/2/premiumGeocode/3401 S Lamar Blvd, Austin, TX.json?&countrySet=US&key={Your_API_Key}&unit=apt 3441

See the TomTom Premium 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": "3401 s lamar blvd austin tx", //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
    "content": "premium" //Indicates if premium content returned in any results.
11

12
  },
13
  "results": [
14
    {
15
        "content": "premium", //Indicates if premium content returned in this result.
16
      "type": "Point Address", //responses type (see table of types above)
17
      "id": "NL/PAD/p0/3802262", //non-stable id for this document (might change in subsequent release)
18
      "score": 13.2504415512,
19
      "matchConfidence": {
20
      "score": 1 //Represents overall textual match score, in the range of [0..1], where 1 means perfect match and 0 - no match.
21
      },
22
      "address": {
23
        "streetNumber": "3401",
24
        "streetName": "South Lamar Boulevard",  //The street name.
25
        "municipality": "Austin", //City / Town
26
        "countrySubdivision": "TX",  //State or Province
27
        "postalCode": "78704", //Postal Code / Zip Code
28
        "extendedPostalCode": "78704-5805", //Extended postal code (availability dependent on region).
29
        "countryCode": "US", //A country's code (Note: This is a two-letter code, not a country name.).
30
        "country": "United States", //Country name
31
        "countryCodeISO3": "USA" //ISO alpha-3 country code
32
        "freeformAddress": "3401 South Lamar Boulevard, Austin, TX 78704", //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.
33
        "localName": "Austin", //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.
34
        "unit": "3441", //The unit number of the address.
35
      },
36
      "addressDetails": {
37
               "numberOfUnits": 279, //The number of units in the building.
38
               "numberOfBuildings": 1, //The number of buildings in the complex.
39
               "floorNumber": 4, //The floor number of the address.
40
               "hasElevator": true, //Indicates whether the building has an elevator.
41
               "hasStair": true, //Indicates whether the building has stairs.
42
               "hasParking": true, //Indicates whether the building has parking.
43
               "wallHeight": 3 //The height of the wall.
44
            },
45
      "position": {
46
        "lat": 52.37727,
47
        "lon": 4.90943
48
      },
49
      "viewport": {
50
        "topLeftPoint": {
51
          "lat": 52.37817,
52
          "lon": 4.90796
53
        },
54
        "btmRightPoint": {
55
          "lat": 52.37637,
56
          "lon": 4.9109
57
        }
58
      },
59
      "entryPoints": [
60
              {
61
                "type": "route",
62
                "functions": [
63
                  "PARKING" //The function of the entry point, indicating Point to be PARKING
64
                ],
65
                "pathToNext": "WALKING", //The path to the next entry point, indicating WALKING
66
                "position": {
67
                  "lat": 30.24054777888027,
68
                  "lon": -97.78596058222561
69
                }
70
              },
71
              {
72
                "type": "route",
73
                "functions": [
74
                  "ENTRANCE" //The function of the entry point, indicating Point to be ENTRANCE
75
                ],
76
                "pathToNext": "WALKING", //The path to the next entry point, indicating WALKING
77
                "position": {
78
                  "lat": 30.240719797674036,
79
                  "lon": -97.78579765954056
80
                }
81
              },
82
              {
83
                "type": "route",
84
                "functions": [
85
                  "ELEVATOR" //The function of the entry point, indicating Point to be ELEVATOR
86
                ],
87
                "pathToNext": "WALKING", //The path to the next entry point, indicating WALKING
88
                "position": {
89
                  "lat": 30.24062750793042,
90
                  "lon": -97.78585748105236
91
                }
92
              }
93
            ]
94
    }
95
  ]
96
}