Mapcode API
Free Mapcode API with no key: turn any latitude and longitude into a short, memorable location code, and decode codes back to coordinates. Tested example and live response.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the Mapcode API?
The Mapcode API is a free, key-free service that converts coordinates into short alphanumeric location codes and back again. A mapcode is typically four to seven characters within a territory, resolves to roughly five metres, and works anywhere on Earth including places with no street addresses.
Mapcode was released into the public domain by its inventors in 2001 and later adopted by the Stichting Mapcode Foundation, which is why it has no licensing story to worry about — unlike the better-known commercial alternatives in the same space. The algorithm is open, several open-source implementations exist, and the public REST service documented here is simply a convenient hosted version of it.
The response repays a careful read. You get a `local` mapcode that is short but only unambiguous inside its stated territory, an `international` one that is longer and globally unique, and a `mapcodes` array listing every valid encoding of the point — because a location near a territory border legitimately has several. Decoding requires the territory alongside a local code; skip it and a code like "49.4V" is meaningless, since the same string is valid in dozens of territories.
Quick facts
- Base URL
https://api.mapcode.com/mapcode- Authentication
- No key or account. The mapcode algorithm is public domain; the hosted REST service is provided free by the Mapcode Foundation.
- Rate limit
- No published quota. The service is community-hosted, so keep volumes reasonable or run the open-source implementation yourself.
- Pricing
- Free. The algorithm itself is public domain and can be self-hosted.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the Mapcode API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Encode a latitude and longitude as a mapcode
GET https://api.mapcode.com/mapcode/codes/52.376514,4.908543
curl 'https://api.mapcode.com/mapcode/codes/52.376514,4.908543'const res = await fetch("https://api.mapcode.com/mapcode/codes/52.376514,4.908543");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://api.mapcode.com/mapcode/codes/52.376514,4.908543", timeout=20)
res.raise_for_status()
print(res.json()){
"local": {
"mapcode": "49.4V",
"territory": "NLD"
},
"international": {
"mapcode": "VHXGB.1J9J"
},
"mapcodes": [
{
"mapcode": "49.4V",
"territory": "NLD"
},
{
"mapcode": "G9.VWG",
"territory": "NLD"
},
{
"mapcode": "DL6.H9L",
"territory": "NLD"
},
{
"mapcode": "P25Z.N3Z",
"territory": "NLD"
},
{
"mapcode": "VHXGB.1J9J"
}
],
"territories": [
{
"alphaCode": "NLD"
}
]
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
codes | path | Required | `/codes/{lat},{lon}` encodes a coordinate pair into every valid mapcode for the point. 52.376514,4.908543 |
coords | path | Optional | `/coords/{mapcode}` decodes a mapcode back to latitude and longitude. NLD 49.4V |
territory | query | Optional | Territory context for decoding a local code. Required unless the code is international. NLD |
include | query | Optional | `territory` adds the full territory name; `alphabet` returns the code in another script. territory |
precision | query | Optional | 0 to 8. Higher precision appends characters and narrows the resolved area below five metres. 2 |
Response fields
local.mapcodestring- The shortest code for the point, valid only within `local.territory`.
local.territorystring- Three-letter territory the local code belongs to — the context without which the code cannot be decoded.
international.mapcodestring- Globally unique code needing no territory. Longer, but unambiguous anywhere.
mapcodesarray- Every valid encoding of the point, ordered shortest first. Points near a border legitimately have several.
territoriesarray- Territories the point falls within, which is what makes multiple encodings possible.
What you can build with the Mapcode API
- Give a short shareable code to a location with no street address
- Label field sites, delivery points or meeting spots in five characters
- Add a compact location reference to receipts, tickets or SMS messages
- Store a human-readable position alongside raw coordinates in a database
- Provide addressing in regions where formal street addressing is absent
Common errors and how to fix them
A local mapcode will not decode
You sent it without its territory.
Fix: Local codes are only unique within a territory. Pass `territory=NLD` alongside the code, or use the international form which needs no context.
Several mapcodes returned for one point
Not an error — points near territory borders have multiple valid encodings.
Fix: Use `local` for brevity within a known region and `international` when the code will travel. The `mapcodes` array shows the full set.
Decoded position is a few metres off
Standard mapcode precision is about five metres.
Fix: Add `precision=2` when encoding to append characters and tighten the resolution. The trade is a longer code.
400 on a malformed coordinate
The path expects `lat,lon` with a comma and no space.
Fix: URL-encode nothing but the comma if your client insists; a space in the path is rejected outright.
Mapcode API — frequently asked questions
Is the Mapcode API free?
Yes, free with no key or account. The mapcode algorithm itself is public domain, and the hosted REST service is run free by the Mapcode Foundation — you can also self-host the open-source implementation.
How precise is a mapcode?
A standard mapcode resolves to roughly five metres. The `precision` parameter appends up to eight extra characters to narrow it further, trading brevity for accuracy.
Why do I get more than one mapcode for a point?
Because a location can fall inside more than one territory context — a point near a national or state border encodes validly in each. The shortest local code and the globally unique international code are both returned, plus the full list.
How does mapcode compare with what3words?
Mapcode is public domain and self-hostable with no licence to negotiate; what3words is proprietary and requires an API key. Mapcode produces alphanumeric codes rather than word triples, which are harder to say aloud but shorter to type.
Tools that pair with this API
Coordinate Converter
Convert GPS coordinates between decimal degrees, degrees-minutes-seconds and decimal minutes instantly. Paste any format like 40°26'46"N and copy the result.
Decimal to DMS Converter
Convert decimal degrees to degrees, minutes and seconds. Choose the seconds precision, see the component breakdown and bulk-convert a whole list.
DMS to Decimal Converter
Convert degrees, minutes and seconds to decimal degrees. Enter D/M/S with a hemisphere, or bulk-paste many DMS coordinates and convert them all at once.
Mapcode is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.