My Geocode

TomTom Search drop-in replacement

TomTom's Geocode, Reverse Geocode and Fuzzy Search endpoints answer at tomtom.mygeocode.com with the same summary and results structure, including the freeformAddress field most integrations display.

Change one hostname

Original host
  • api.tomtom.com
Use insteadtomtom.mygeocode.com
Key parameterkey (optional: any address gets 2,500 requests a day with no key; put your My Geocode key here for credit, packages and a usage history)
Before
curl "https://api.tomtom.com/search/2/geocode/Damrak%201%2C%201012%20LG%20Amsterdam.json?key=YOUR_TOMTOM_KEY"
After
curl "https://tomtom.mygeocode.com/search/2/geocode/Damrak%201%2C%201012%20LG%20Amsterdam.json?key=YOUR_MYGEOCODE_KEY"

Why people move

TomTom's free tier is 2,500 transactions a day, the same as ours, but a transaction there can cost several credits. Here every call is one request, and paid usage has a flat option.

Same free allowance, key or not. Requests to tomtom.mygeocode.com count toward the same 2,500 free requests a day your address, or your key, gets on our own endpoints. Above that, prepaid credit at €0.0001 per request, or €50 a month for an Unlimited key. Signing up takes a name and an email address, and no card.

See pricing Get a free key

Endpoints

Path on tomtom.mygeocode.comWhat it doesBacked by
/search/2/geocode/{query}.jsonGeocodeForward geocoding
/search/2/structuredGeocode.json?countryCode=...&streetName=...Structured geocodeForward geocoding
/search/2/reverseGeocode/{lat},{lon}.jsonReverse geocodeReverse geocoding
/search/2/search/{query}.json?typeahead=trueFuzzy search with typeaheadAddress autocomplete

Example response

This is what the request above returns. Field names, nesting and types follow TomTom. Only the data behind them is ours.

Response from tomtom.mygeocode.com
{
  "summary": {
    "query": "damrak 1, 1012 lg amsterdam",
    "queryType": "NON_NEAR",
    "queryTime": 1,
    "numResults": 2,
    "offset": 0,
    "totalResults": 2,
    "fuzzyLevel": 1
  },
  "results": [
    {
      "type": "Point Address",
      "id": "6f986fb91fcb522baf3727",
      "score": 8.2,
      "matchConfidence": { "score": 0.82 },
      "address": {
        "streetNumber": "1",
        "streetName": "Damrak",
        "municipality": "Amsterdam",
        "postalCode": "1012 LG",
        "countryCode": "NL",
        "country": "The Netherlands",
        "countryCodeISO3": "NLD",
        "freeformAddress": "Damrak 1, 1012 LG Amsterdam",
        "localName": "Amsterdam"
      },
      "position": { "lat": 52.37715, "lon": 4.89803 },
      "viewport": {
        "topLeftPoint": { "lat": 52.37766, "lon": 4.89753 },
        "btmRightPoint": { "lat": 52.37664, "lon": 4.89855 }
      },
      "entryPoints": [{ "type": "main", "position": { "lat": 52.37715, "lon": 4.89803 } }]
    },
    {
      "type": "Point Address",
      "id": "7831aa047f87458a55f023",
      "score": 7.7,
      "matchConfidence": { "score": 0.77 },
      "address": {
        "streetNumber": "1",
        "streetName": "Damraksteeg",
        "municipality": "Amsterdam",
        "postalCode": "1012 LP",
        "countryCode": "NL",
        "country": "The Netherlands",
        "countryCodeISO3": "NLD",
        "freeformAddress": "Damraksteeg 1, 1012 LP Amsterdam",
        "localName": "Amsterdam"
      },
      "position": { "lat": 52.37361, "lon": 4.89335 },
      "viewport": {
        "topLeftPoint": { "lat": 52.37411, "lon": 4.89285 },
        "btmRightPoint": { "lat": 52.37311, "lon": 4.89387 }
      },
      "entryPoints": [{ "type": "main", "position": { "lat": 52.37361, "lon": 4.89335 } }]
    }
  ]
}

Details and differences

No key is needed for the first 2,500 requests a day. To use a My Geocode key, put it where your TomTom key went: the key query parameter. The X-API-Key header, Authorization: Bearer and HTTP Basic authentication (the key as the user name) work on every host too, so client libraries that authenticate their own way keep working unchanged.

  • Free form, structured and reverse geocoding are all routed, plus the search endpoint.
  • Answers keep TomTom’s summary and results shape.
  • Batch Search works both ways. POST /search/2/batch/sync.json answers up to 100 batchItems at once in TomTom’s shape (statusCode and response per item, summary). POST /search/2/batch.json takes up to 10,000, answers 202 with a Location header, and the result is fetched from there. Each batch item counts as one request, as TomTom counts them; a batch larger than what is left of the allowance is refused whole with TomTom’s 429, and fetching a stored result counts nothing.
  • Put .xml where the path ends in .json for an XML answer from geocode, structured geocode, reverse geocode and search.
  • mapcodes=Local,International,Alternative adds the point’s mapcodes, and search with timeZone=iana adds poi.timeZone.

If your client depends on a field or behaviour that is not listed here, tell us. Compatibility gaps get fixed quickly because they are usually small.

Other drop-in hosts

How the drop-ins work, the overview, and the JavaScript library drop-ins.