Mapcode REST API
The Mapcode Foundation provides a free public REST API at https://api.mapcode.com/mapcode.
This is the free REST API for the Mapcode Foundation, intended for demonstration purposes only. If you want to use this API for production purposes, or in a high-frequency application, please consider hosting your own Mapcode REST API server. It is open-source and available at https://github.com/mapcode-foundation/mapcode-rest-api.
Conversion
GET
/mapcode/codes/{lat},{lon} Convert coordinates (latitude/longitude) to mapcode(s) | Name | In | Required | Description |
|---|---|---|---|
lat | path | Yes | Latitude, range -90 to 90 — e.g. 52.3731 |
lon | path | Yes | Longitude, range -180 to 180 — e.g. 4.8922 |
precision | query | No | Extra precision digits, 0–8. Default: 0 — e.g. 0 |
territory | query | No | Restrict results to a territory (name or alphacode) — e.g. NLD |
country | query | No | 2 or 3 character ISO-3166 country code — e.g. NL |
alphabet | query | No | Return mapcodes in a specific alphabet — e.g. ROMAN |
include | query | No | Comma-separated extras to include: offset, territory, alphabet, rectangle — e.g. territory |
GET
/mapcode/coords/{code} Convert a mapcode to coordinates (latitude/longitude) | Name | In | Required | Description |
|---|---|---|---|
code | path | Yes | Mapcode, optionally prefixed with territory (e.g. NLD XX.XX) — e.g. NLD XX.XX |
context | query | No | Territory for disambiguation (e.g. NLD, USA) — e.g. NLD |
include | query | No | Optional extras: rectangle — e.g. rectangle |
Territories
GET
/mapcode/territories List all supported territories | Name | In | Required | Description |
|---|---|---|---|
offset | query | No | Start position (negative values count from end) — e.g. 0 |
count | query | No | Maximum number of items to return — e.g. 10 |
GET
/mapcode/territories/{territory} Get details for a single territory | Name | In | Required | Description |
|---|---|---|---|
territory | path | Yes | Territory name or alphacode (e.g. NLD, USA) — e.g. NLD |
context | query | No | Parent territory for disambiguation (e.g. USA for US states) — e.g. USA |
Internationalization
GET
/mapcode/alphabets List all supported alphabets | Name | In | Required | Description |
|---|---|---|---|
offset | query | No | Start position — e.g. 0 |
count | query | No | Maximum number of items to return — e.g. 10 |
GET
/mapcode/alphabets/{alphabet} Get details for a single alphabet | Name | In | Required | Description |
|---|---|---|---|
alphabet | path | Yes | Alphabet name (e.g. ROMAN, GREEK, ARABIC) — e.g. ROMAN |
Utilities
GET
/mapcode/version Get the API and library version information GET
/mapcode/status Health check — returns HTTP 200 if the service is available GET
/mapcode/metrics Get system metrics