Mapcode REST API

​The Mapcode Foundation provides a Mapcode REST API at: 

 

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:

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:

Compile the source code and create a WAR file using:

cd <source-dir>

mvn clean install

The build process should end with the message "BUILD SUCCESS".

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:

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

Using the free Mapcode REST API

We encourage you to experiment with our free hosted Mapcode REST API.

If your business relies on this service, please be aware of the following.

Our web service is a free service, but the the Mapcode Foundation cannot guarantee the availability of this service and do not accept any claims on its availability.

If you are interested in using the Mapcode REST API for professional purposes, or in high-availability or high-demands contexts, you should consider using a professional Mapcode conversion provider.

TomTom offers such an API here. Or consider self-hosting the service on a cloud platform, like Amazon Elastic Beanstalk, Microsoft Azure AppServic, Google App Engine, DigitalOcean Droplets or any other.

Alternatively, you may wish to convert locations to mapcodes and v.v. using our software libraries and avoid the cost of cloud computing altogether.

Contact us for more information on the possibilities.

Meanwhile, enjoy our free service!

Service usage data collection

We always seek to improve our open-source software for mapcode support.

This is why the Mapcode Foundation may collect service usage data of the free Mapcode REST API service.

 

Any data collected is only used for improving our open-source software and never used for commercial purposes.

Copyright © 2019, Stichting Mapcode Foundation

  • c-facebook