Sorry, you need to enable JavaScript to visit this website.

Pinpoint Locations with Mapcode Support in the TomTom Search API

Mapcodes are a free, open way to make every house or location on Earth addressable by a short code. In this article, we’ll take a closer look at Mapcode and demonstrate how the TomTom Search API provides direct support for finding locations with mapcodes

Why Mapcodes?

The Mapcode system was designed specifically as a free, brandless, international standard for representing any location on the surface of the Earth by a short, easy-to-recognise, remember-and-communicate “code”, usually consisting of between four and seven letters and digits. The short length of a mapcode is the key differentiating factor between coordinates and other codes. They are precise to a few meters, which is good enough for everyday use.

The advantage of mapcodes in mapping applications is the ease of very precisely identifying locations in the way we’d use something complicated like latitude and longitude coordinates, but instead using a very simple code that’s easier to remember than a phone number.

In this article, we’ll:

  • Take a closer look at Mapcode
  • Learn how to generate mapcodes
  • Examine some potential scenarios where mapcodes are useful
  • See how mapcodes are support by TomTom location APIs

What is a Mapcode?

A mapcode consists of two groups of letters and digits, separated by a dot. An example of a mapcode is: 49.4V. This short code is sufficient as long as it is clear what country or state the mapcode belongs in. It is recommended to explicitly specify the country, for example, Netherlands 49.4V.​

Mapcodes are a free, open way to make every house or location on Earth addressable by a short code. With nothing else except your mapcode, for instance, a navigation system will bring someone to within meters of your front door. Mapcodes are more precise and more flexible than the address on a business card. You can pick the location you want to associate with your address — for example, the main entrance or entrance to a car park. In countries where roads and houses have no names or addresses, you can use a mapcode instead. 

Mapcodes were invented by TomTom founders Pieter Geelen and Harold Goddijn in 2001, and they donated it to the public domain in 2008. Mapcode data and algorithms are maintained by the Mapcode Foundation, which freely licenses mapcode source code and specifications to organizations. Unlike similar technologies like What3Words, which are managed by commercial companies, Mapcodes are entirely free and open and are based on logical cell combinations.

The Mapcode site has a location translation demo with Mapcode REST API at: https://api.mapcode.com/mapcode

http get https://api.mapcode.com/mapcode/codes/48.858370,2.294481

The response will return all available mapcodes.

<mapcodes>
  <local>
    <mapcode>4J.P2</mapcode>
    <territory>FRA</territory>
  </local>
  <international>
    <mapcode>VHPM8.QYCK</mapcode>
  </international>
  <mapcodes>
    <mapcode>
      <mapcode>4J.P2</mapcode>
      <territory>FRA</territory>
    </mapcode>
    <mapcode>
      <mapcode>FH.N7T</mapcode>
      <territory>FRA</territory>
    </mapcode>
    <mapcode>
      <mapcode>H60.TKL</mapcode>
      <territory>FRA</territory>
    </mapcode>
    <mapcode>
      <mapcode>HCPW.PQV</mapcode>
      <territory>FRA</territory>
    </mapcode>
    <mapcode>
      <mapcode>VHPM8.QYCK</mapcode>
    </mapcode>
  </mapcodes>
</mapcodes>

The response includes:

  • The local mapcode for the specific location, which is the shortest mapcode
  • The international mapcode, which is a worldwide unique mapcode, but it is also the longest mapcode
  • The mapcodes section includes a list of all available mapcodes, including the international one, for a specific location.

A mapcode also can be converted to a latitude/longitude location. For example:

http get https://api.mapcode.com/mapcode/coords/VHPM8.QYCK

The response will return the latitude, longitude location. International codes are globally unique, so this always works. 

<point>
  <latDeg>48.858368</latDeg>
  <lonDeg>2.2944905</lonDeg>
</point>

If you use a shorter code, you’ll need to provide the relevant territory as a 'context'. For example:

http get https://api.mapcode.com/mapcode/coords/4J.P2?context=FRA

Scenarios Where Mapcodes are Useful

You might be wondering why we need another way to identify a location when latitude and longitude or just an address has been working pretty well most of the time. In many situations, coordinates or addresses get the job done. But here are just a few scenarios where addresses just aren’t as helpful for finding a location as a mapcode could be.

Emergency Services

Concise, accurate mapcodes can save lives by ensuring that emergency services are directed to the correct location as quickly as possible. The challenges faced by emergency services failing to find addresses for a patient, or police not making it in time to a crime scene due to lack of address information is critical in many areas. 

Street names are misleading sometimes — there may be more than one street with the same name — and sometimes locations don’t have obvious addresses or landmarks. Mapcodes provide a great solution for emergency service because they are short and unique to any location.

Mapcodes will enable emergency services to identify any location on the planet accurately, within metres, even in rural, industrial, or undeveloped areas where address information is vague, inaccurate, or nonexistent.

Mapping in Rural or Undeveloped Locales

Imagine having no fixed or defined address. You would not be able to partake in many of the day-to-day activities we so often take for granted. In some sense, having an address means also having an identity as a citizen. 

However, about four billion people on Earth do not have an address. Yet these people may want to do things that traditionally require an address, such as receiving mail and deliveries, receiving emergency aid, or conducting business. 

Mobile devices are becoming ubiquitous even the most remote locations, giving people the ability to find and share mapcodes easily, regardless of street address (or no address at all). 

Survey, Logistics, and Geocaching Tasks

The vast number of homes and businesses without a street address poses many broad challenges, and specifically to the continued expansion of the market for vehicle navigation and location-based services, like survey, logistics, and geocaching tasks. Mapcode creates a grid accurate to within five square meters anywhere on the Earth to overcome these obstacles to navigation.    

Although latitude/longitude coordinates can be more accurate, they’re also user-unfriendly and difficult to remember. They don’t lend themselves to printing on a business card or sending in a text message, as mapcodes do. 

Mapcodes are being adopted by mapping companies, including TomTom and are increasingly supported by mapping software, APIs, and navigation systems.

Disconnects specific locations from postal data-based location

Postal codes are assigned to areas by postal authorities and typically follow existing jurisdictional boundaries. However, a postal address is not an explicit definition of location and can change over time. Postal addresses are not sufficiently precise for many purposes. For example, the address of a park will bring you only to its main entrance, not to a particular bench. 

Mapcodes are precise to a few meters. Every location on Earth can be represented by a mapcode. Mapcodes allow you to identify non property based locations, or locations that don’t have a postal address. 

Mapcode Support in the TomTom Search API

The TomTom Search API includes direct support for translating mapcodes to and from other search criteria. For example, the Reverse Geocoding endpoint of Search API gives users a tool to translate a coordinate into a human-understandable street address, street element, or geography, and mapcodes as well.

For example, let’s get the mapcodes for Federation Square, Melbourne, Australia. The latitude and longitude of Federation Square is -37.817798, 144.968714.

The request parameter “mapcodes” enables the return of mapcodes. It takes optional flags to filter the response to only show selected mapcode types, including Local, International, or Alternative.

To send a Reverse Geocoding request with local and international mapcodes, we format the request like this:

https://api.tomtom.com/search/2/reverseGeocode/-37.817798,144.968714.json?mapcodes=Local,International&key=*****

(This example won’t actually work as written. You will have to enter your own API key where I’ve included *****.)

The JSON-formatted response looks like this:

{
  "summary": {
    "queryTime": 9,
    "numResults": 1
  },
  "addresses": [
    {
      "address": {
        "routeNumbers": ["30"],
        "street": "Flinders Street",
        "streetName": "Flinders Street",
        "countryCode": "AU",
        "countrySubdivision": "Victoria",
        "countrySecondarySubdivision": "Melbourne",
        "municipality": "Melbourne",
        "postalCode": "3000",
        "municipalitySubdivision": "Melbourne CBD",
        "country": "Australia",
        "countryCodeISO3": "AUS",
        "freeformAddress": "Flinders Street, Melbourne Melbourne CBD, Victoria, 3000",
        "boundingBox": {
          "northEast": "-37.817179,144.968673",
          "southWest": "-37.817262,144.968380",
          "entity": "position"
        }
      },
      "position": "-37.817238,144.968460",
      "mapcodes": [
        {
          "type": "Local",
          "fullMapcode": "AU-VIC KL.B2",
          "territory": "AU-VIC",
          "code": "KL.B2"
        }, 
        {
          "type": "International",
          "fullMapcode": "6WZ4V.SJLP"
        }
      ]
    }
  ]
}
 

From the response, you can see that the international mapcode is 6WZ4V.SJLP, and the local mapcode is KL.B2.

TomTom Search API Fuzzy Search is the default search mode for addresses, address ranges, streets, and general points of interest. This search supports both latitude/longitude coordinates and mapcodes.

So if we send a request to the Search API with the mapcode of Melbourne Federation Square, we’ll get an exact match. We format the request like this:

https://api.tomtom.com/search/2/search/AU-VIC%20%20KL.B2.json?idxSet=Addr&key=*****

(Again, you will have to enter your own API key where I’ve included *****.)

The JSON-formatted response looks like this:

{
  "summary": {
    "query": "",
    "queryType": "NON_NEAR",
    "queryTime": 18,
    "numResults": 2,
    "offset": 0,
    "totalResults": 2132,
    "fuzzyLevel": 1,
    "geoBias": {
      "lat": -37.8172,
      "lon": 144.9684215
    }
  },
  "results": [
    {
      "type": "Address Range",
      "id": "AU/ADDR/p0/305904",
      "score": -0.06005,
      "dist": 59.82334654220987,
      "address": {
        "streetName": "Flinders Street, 30",
        "municipalitySubdivision": "Melbourne CBD",
        "municipality": "Melbourne",
        "countrySecondarySubdivision": "Melbourne",
        "countrySubdivision": "Victoria",
        "postalCode": "3000",
        "countryCode": "AU",
        "country": "Australia",
        "countryCodeISO3": "AUS",
        "freeformAddress": "Flinders Street, Melbourne Melbourne CBD, Victoria, 3000"
      },
      "position": {
        "lat": -37.81735,
        "lon": 144.96753
      },
      "viewport": {
        "topLeftPoint": {
          "lat": -37.8175,
          "lon": 144.96807
        },
        "btmRightPoint": {
          "lat": -37.81735,
          "lon": 144.96753
        }
      },
      "addressRanges": {
        "rangeLeft": "183 - 183",
        "from": {
          "lat": -37.81735,
          "lon": 144.96753
        },
        "to": {
          "lat": -37.8175,
          "lon": 144.96807
        }
      }
    }, 
    {
      "type": "Address Range",
      "id": "AU/ADDR/p0/300991",
      "score": -0.12055,
      "dist": 121.01241726062317,
      "address": {
        "streetName": "Flinders Lane",
        "municipalitySubdivision": "Melbourne CBD",
        "municipality": "Melbourne",
        "countrySecondarySubdivision": "Melbourne",
        "countrySubdivision": "Victoria",
        "postalCode": "3000",
        "countryCode": "AU",
        "country": "Australia",
        "countryCodeISO3": "AUS",
        "freeformAddress": "Flinders Lane, Melbourne Melbourne CBD, Victoria, 3000"
      },
      "position": {
        "lat": -37.81612,
        "lon": 144.9681
      },
      "viewport": {
        "topLeftPoint": {
          "lat": -37.81615,
          "lon": 144.96823
        },
        "btmRightPoint": {
          "lat": -37.81612,
          "lon": 144.9681
        }
      },
      "addressRanges": {
        "rangeRight": "188 - 188",
        "from": {
          "lat": -37.81612,
          "lon": 144.9681
        },
        "to": {
          "lat": -37.81615,
          "lon": 144.96823
        }
      }
    }
  ]
}

The response includes the address: Flinders Street, Melbourne CBD, Victoria, 3000.

Conclusion

A mapcode represents a specific location, to within a few meters. Every location on Earth can be represented by a mapcode. Mapcodes are designed to be short, easy to recognize, remember and communicate. Visit the Mapcode website for more information.

As you’ve seen, the TomTom Search API supports mapcodes directly. You can search geographies, point addresses, address ranges, streets, cross streets and points of interest by mapcodes. Visit TomTom Search API Documentation for more information.

First published: 
Tuesday, October 22, 2019 - 01:55
Last edited: 
Friday, October 25, 2019 - 23:27