Developer tools

Build with Mapcode

Start with the REST API if you want to try mapcodes quickly: integration is simple and you can get results in minutes. Use a library, like TypeScript, when you need local or offline encoding, lower latency, no network dependency, or no API data-transfer cost.

Start with the REST API View full API docs

Recommended order

  1. REST API for the fastest first integration.
  2. TypeScript when you want local encoding in web or Node.js apps.
  3. Python for scripts, analysis and backend workflows.
  4. Java for existing JVM applications.

REST API quick start

Use the public REST API to prove the encode and decode flow before choosing a deeper integration. These examples use Mount Kilimanjaro as a neutral landmark in Africa.

1. Coordinates to mapcode

Request mapcodes for a coordinate near Mount Kilimanjaro and restrict the local result to Tanzania.

Request 
GET https://api.mapcode.com/mapcode/json/codes/-3.0674,37.3556?territory=TZA
Key response 
{
  "local": {
    "mapcode": "86.W6V5",
    "territory": "TZA"
  }
}

2. Mapcode to coordinates

Decode the local mapcode back to the center point of the represented area.

Request 
GET https://api.mapcode.com/mapcode/json/coords/TZA%2086.W6V5
Key response 
{
  "latDeg": -3.0673755,
  "lonDeg": 37.3555635
}

Small coordinate differences after decoding are normal because a mapcode represents a small area rather than the exact original input point.

Open full REST API documentation

Libraries

Use a library when you want mapcode encoding and decoding inside your own application without depending on network calls.

TypeScript

The recommended library for web, Node.js and TypeScript projects.

npm package Source on GitHub

Install 
npm install mapcode-ts
Encode and decode 
import { encodeToShortest, decode, Territory } from "mapcode-ts";

const code = encodeToShortest(-3.0674, 37.3556, Territory.TZA);
console.log(code.getCodeWithTerritory()); // TZA 86.W6V5

const point = decode("TZA 86.W6V5");
console.log(point.getLatDeg(), point.getLonDeg());

Python

Use Python for scripts, data workflows and backend services.

PyPI package Source on GitHub

Install 
pip install mapcode
Encode and decode 
import mapcode

print(mapcode.encode(-3.0674, 37.3556, "TZA")[0])
print(mapcode.decode("TZA 86.W6V5"))

Java

Use Java when you are integrating mapcodes into an existing JVM application.

Maven metadata Source on GitHub Java documentation

Maven dependency 
<dependency>
  <groupId>com.mapcode</groupId>
  <artifactId>mapcode</artifactId>
  <version>2.4.19</version>
</dependency>
Encode and decode 
import com.mapcode.Mapcode;
import com.mapcode.MapcodeCodec;
import com.mapcode.Point;
import com.mapcode.Territory;

Mapcode code = MapcodeCodec.encodeToShortest(-3.0674, 37.3556, Territory.TZA);
System.out.println(code.getCodeWithTerritory());

Point point = MapcodeCodec.decode("TZA 86.W6V5");
System.out.println(point.getLatDeg() + ", " + point.getLonDeg());

Other tools

These tools remain available, but most new technical integrations should start with REST, TypeScript or Python.

Command-line utility

The C/C++ source includes a cross-platform command-line utility for encoding and decoding mapcodes.

MyMapcodes.com

You may wish to use MyMapcodes.com to find mapcodes easily, also on your phone. MyMapcodes is a free, unaffiliated website.

Legacy tools

Legacy Windows tools remain available for convenience, but they are not the recommended path for new integrations.

Encode location -33.93, 18.8: 
mapcode -e -33.93, 18.8
Decode it again: 
mapcode -d ZAF WK.QV5
Convert a mapcode to coordinates: 
=WEBSERVICE("https://api.mapcode.com/mapcode/xml/coords/Q4.HGY?context=NLD")
Convert coordinates back to mapcodes: 
=WEBSERVICE("https://api.mapcode.com/mapcode/xml/codes/52.460897,5.1074585")