Mapcode REST API

​The Mapcode Foundation provides a Mapcode REST API at: 

 

• https://api.mapcode.com/mapcode

​

This free web service is provided as an example for demonstration purposes only. We'll try hard to provide a stable and decent service and we encourage you to experiment with it, but please remember we may decide to discontinue the service at some point. Please read the additional notice in the blue text box for more info.

​

Online mapcode conversion API's, for professional services, offered by commercial parties are listed at the bottom of this page.

​

You can try out our service using curl, by typing:

​

curl -X GET https://api.mapcode.com/mapcode

​

This provides you some help text on how to further use this web service. The source code for the web service is open-source and available at:

​

• https://github.com/mapcode-foundation/mapcode-rest-service

​

You can use it, run it in your own cloud and adapt it in any way you wish to have the web service  match your requirements.

​

The examples below show you how to use the web service and how to deploy it in your own cloud, if your business relies on the service to be always available.

​

Example: convert location to mapcode

For example, to convert a latitude/longitude pair of 48.858370, 2.294481(Eiffeltower in Paris) to a mapcode:

​

curl -X GET https://api.mapcode.com/mapcode/codes/48.858370,2.294481

​

This produces the following result:

​

{

    "international": {

        "mapcode": "VHPM8.QYCK"

    },

    "local": {

        "mapcode": "4J.P2",

        "territory": "FRA"

    },

    "mapcodes": [

        {

            "mapcode": "4J.P2",

            "territory": "FRA"

        },

        {

            "mapcode": "FH.N7T",

            "territory": "FRA"

        },

        {

            "mapcode": "H60.TKL",

            "territory": "FRA"

        },

        {

            "mapcode": "HCPW.PQV",

            "territory": "FRA"

        },

        {

            "mapcode": "VHPM8.QYCK"

        }

    ]

}

​

The response always contains three sections:

• International: This is a world-wide unique mapcode. It is also the longest mapcode (of 10 characters in total). Use this code only if you have no idea what the regional context for a code is. For systems that are used in a specific country or state, we recommend using the shorter codes.

• Local: This is simply the shortest code from all the alternatives in the "Mapcodes" section. Please be aware that the code may use an unexpected territory code near border, where different mapcodes may be available for adjacent territories.

• Mapcodes: This is a list of all available mapcodes, including the international one, for a specific location. If your system is aware of its geographical context (for example, if the system is a postal code system for a country), then you should look for the shortest code in this list for your territory and use that code.

​

Example: convert mapcode to location

To convert an international mapcode back to a location, you can use this:

​

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

​

This returns the latitude, longitude for the location:

​

{

    "latDeg": 48.858368,

    "lonDeg": 2.2944905

}

​

International codes are globally unique, so this always works. If you use a shorter code, which we usually recommend, because they are easier to remember and communicate, you need to provide the relevant territory as a 'context' to disambiguate the mapcode:

​

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

​

This returns:

​

{

    "latDeg": 48.85838,

    "lonDeg": 2.29444

}

​

You may notice the returned locations may not be exactly the same. This is because the grids used for the international and shorter codes are different. The returned locations are always very close to each other, however (within 5 meters).

​

Example: deploy on Amazon Elastic Beanstalk

If you wish to deploy the Mapcode REST API on Amazon, we recommend using Elastic Beanstalk.  This section describes roughly how to do so.

​

Prerequisites for compiling the service are:

• Maven

• JDK 8 or higher

• Amazon AWS account

​

You can create the Mapcode REST API binaries and deploy them as follows:

 

Get the source code for the Mapcode REST API at:

• https://github.com/mapcode-foundation/mapcode-rest-service/releases

​

Compile the source code and create a WAR file using the instructions in the README.md file.

​

Login to Amazon AWS, go to the Services menu and select Elastic Beanstalk. Choose Actions and Create environment.

​

Create an Elastic Beanstalk environment with the following minimum configuration:

• 2 or more instances

• Recommended EC2 instance type: t2.micro or more higher

• Platform: Tomcat running on 64bit Linux 

• No additional disk storage or databases required

• Environment type: load balancing, auto scaling

• Availability zones: any

• Monitor interval: 1 minute

• Health path: /mapcode/status

• Ignore HTTP 4xx: enabled

• Deployment policy: rolling

​

Deploy the Mapcode REST API WAR file to Elastic Beanstalk, which is located at:

​

<source dir>/deployment/target/deployment-x.y.z.war

​

You should now be able to access the Mapcode REST API through the URL provided by Elastic Beanstalk (e.g. my-mapcode.elasticbeanstalk.com).

 

Using REST APIs for professional services

If you plan to use online mapcode REST APIs for professional services that require some form of Service Level Agreement, we suggest you consider the following:

• TomTom provides an online Search API, which offers mapcode conversion as well. They offer a high-availability API, with excellent coding and decoding of mapcodes: 
  https://developer.tomtom.com/products/search-api

• You can host the REST API yourself in a cloud provider of your choice, by building and deploying the open source REST API found here:
  https://github.com/mapcode-foundation/mapcode-rest-service/

​

(If you offer an API to encode/decode mapcodes, please let us know and we'll add you to this list.)