Offline Maps API

_{Last updated: July 24, 2026 | 8 minutes read}

Current version: 1.0.0 | View Release Notes

The Offline Maps API gives applications everything needed to provision and maintain offline map content. It exposes the catalog of downloadable maps — organized by map version and SDK capability — and serves the map files themselves with production-grade download semantics: resumable transfers via HTTP ranges, conditional requests via ETag and Last-Modified, and per-file integrity checksums (CRC32, MD5, SHA-256) so clients can verify every byte they store.

A typical integration follows three steps: query versions to find the map versions compatible with your SDK capability, query file_list to obtain the catalog of a chosen version (world basemap plus per-country and per-state map files), then download the files your user selects — by file path, by content id, or by country.

Authentication Required

All requests require a valid API token and its secret. Requests without a token or without the secret are rejected with 401; requests with an invalid token or a wrong secret are rejected with 403.

Version and Capability Consistency

The world basemap and all regional maps stored on a device must be the same map version. Mixing versions is not supported.
When upgrading from an earlier map version, download the new world basemap first (download=basemap), then re-download every regional map at the new version.
Always request the catalog with the map capability actually supported by your SDK/app version — a higher capability may list maps your SDK cannot read.
Although an SDK/app with a higher capability fully supports older map versions, it is recommended to always use the latest map version available for your capability (map_version=latest).

Endpoints:

GET /offline_maps/versions
GET /offline_maps/file_list
GET /offline_maps/download

Base URL: https://api.magiclane.net/api/v1

All endpoints support GET, HEAD, and POST (application/x-www-form-urlencoded — body fields supplement query parameters).

Migrating from offlinemaps.magiclane.com

This API supersedes the legacy offline maps service at offlinemaps.magiclane.com. Requests map one-to-one onto the new endpoints — parameters and authentication are unchanged:

Legacy request	New endpoint
`/api?capability=...`	`/offline_maps/versions?capability=...`
`/api?capability=...&map_version=...`	`/offline_maps/file_list?capability=...&map_version=...`
`/api?capability=...&map_version=...&download=...` (or `path`, `content_id`, `country_iso`, `country_name`)	`/offline_maps/download` with the same parameters

Authentication

Credentials can be supplied through the Authorization header or through query parameters:

Method	Location	Example
Header	Request header	`-H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"`
Query parameters	URL query string	`?authToken=YOUR_API_TOKEN&authSecret=YOUR_SECRET`

Failure	Status	Body
Token missing	`401`	`Token not found in request !`
Secret missing	`401`	`AUTH_SECRET not found in request !`
Token invalid, expired, or blacklisted	`403`	—
Secret does not match the application	`403`	—

Common Parameters

Parameter	Type	Required	Description
`capability`	integer or `latest`	Yes	The map capability level of your SDK. An SDK with capability R can consume any map version whose capability is less than or equal to R. `latest` selects the highest capability available. A value greater than the maximum supported returns `400`.
`map_version`	string or `latest`	`file_list`, `download`	Map version in `major.minor` form (for example `7.546`). `latest` selects the newest version compatible with the resolved capability.

Versions

Lists all map versions compatible with the given capability, newest first.

Endpoint: GET /offline_maps/versions

Example Request

curl "https://api.magiclane.net/api/v1/offline_maps/versions?capability=latest" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"

Response

{
  "capability": 15,
  "compatible_maps": ["7.546", "7.545", "7.543", "7.541", "7.535"]
}

Field	Description
`capability`	The resolved capability level.
`compatible_maps`	Map versions consumable at that capability, newest first.

Status Codes

Code	Meaning
`200`	Success.
`400`	Wrong or missing `capability` (including capability greater than the maximum supported).
`404`	No compatible map versions available.

File List

Returns the downloadable content catalog of one map version: the world basemap and the individual map files with their geographic attribution and integrity checksums.

Endpoint: GET /offline_maps/file_list

Example Request

curl "https://api.magiclane.net/api/v1/offline_maps/file_list?capability=latest&map_version=7.546" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"

Response

{
  "capability": 15,
  "map_version": "7.546",
  "is_patch": 0,
  "basemap_url": {
    "path": "basemap/WM_7_546.map",
    "size": 194538761,
    "crc32": "ac49b0fc",
    "md5": "0f343b0931126a20f133d67c2b018a3b",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "map_url": [
    {
      "content_id": 553648134,
      "continent": "Europe",
      "country_name": "Netherlands",
      "country_iso": "NLD",
      "path": "NetherlandsOSM_7_546.cmap",
      "size": 1367414149,
      "crc32": "50abc957",
      "md5": "8dfa4b4f0ecf9861e25e213989d7a2fa",
      "sha256": "394bc3162a55b51eaeca6a2be850c3e742a8f8a7cf9ebaa55ce66e64c2536745"
    }
  ]
}

Field	Description
`capability`	Capability level of the returned map version.
`map_version`	The resolved map version.
`is_patch`	`1` when the version is distributed as a patch on top of a base version, `0` otherwise.
`basemap_url`	The world basemap file: `path` (relative to the version), `size` in bytes, and integrity checksums.
`map_url`	Array of downloadable map files. Each entry carries `content_id`, geographic attribution (`continent`, `country_name`, `country_iso`, optional `state`), `path`, `size`, and checksums.

Entries may carry additional catalog fields beyond the ones listed (for example store_visibility); these are passed through from the map catalog unchanged and can be ignored if not needed.

Use the checksums to verify downloaded files: crc32 for a fast check, md5/sha256 for stronger verification.

Status Codes

Code	Meaning
`200`	Success.
`400`	Wrong or missing `capability` or `map_version`.
`404`	The requested map version does not exist or is not compatible with the capability.

Download

Downloads one map file of a version. The file is selected by exactly one of the selectors below.

Endpoint: GET /offline_maps/download

File Selectors

Parameter	Description
`download`	File path as listed in `file_list` (`path` field), for example `NetherlandsOSM_7_546.cmap`. Primary selector; `path` and `file` are aliases. The special value `basemap` downloads the version's world basemap; an explicit `basemap/<file>.map` path is also accepted.
`content_id`	Numeric content id from the `file_list` entry.
`country_iso`	ISO country code from the `file_list` entry. For countries split into states, add `state` — a bare country selector matching several files is rejected as ambiguous.
`country_name`	Country name from the `file_list` entry, same rules as `country_iso`.
`state`	State name, combined with `country_iso` or `country_name`.

String selector values must be URL-encoded — paths with spaces or non-ASCII characters (for example Brazil_São Paulo... or Norway_Bouvet Island...) are decoded by the server before matching.

Example Requests

Download the world basemap:

curl -O "https://api.magiclane.net/api/v1/offline_maps/download?capability=latest&map_version=7.546&download=basemap" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"

Download by file path (URL-encoded):

curl -O "https://api.magiclane.net/api/v1/offline_maps/download?capability=latest&map_version=7.546&download=Brazil_S%C3%A3o%20Paulo_SA.map" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"

Download by country and state:

curl -O "https://api.magiclane.net/api/v1/offline_maps/download?capability=latest&map_version=7.546&country_iso=AUS&state=New%20South%20Wales" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET"

Resume an interrupted download:

curl "https://api.magiclane.net/api/v1/offline_maps/download?capability=latest&map_version=7.546&content_id=553648134" \
  -H "Authorization: Bearer YOUR_API_TOKEN, Secret YOUR_SECRET" \
  -H "Range: bytes=52428800-" \
  -o NetherlandsOSM_7_546.cmap.part

Response Headers

Header	Description
`Content-Type`	`application/octet-stream`
`Content-Disposition`	`attachment; filename="<file>"`
`Content-Length`	Number of bytes in the response body.
`ETag`	Weak validator for the file, for use with `If-None-Match`.
`Last-Modified`	File modification time (RFC 1123 date), for use with `If-Modified-Since`.
`Accept-Ranges`	`bytes` — range requests are supported.
`Content-Range`	Present on `206` responses (`bytes start-end/total`) and on `416` responses (`bytes */total`).
`Cache-Control`	`max-age=172800, no-cache, must-revalidate, no-transform`

Conditional Requests

Send the ETag returned by a previous download in If-None-Match, or the Last-Modified date in If-Modified-Since, to avoid re-downloading unchanged files — the server answers 304 Not Modified. When both headers are present, If-None-Match takes precedence.

Range Requests

Partial downloads and resume are supported through the standard Range header: bytes=start-, bytes=start-end, and the suffix form bytes=-count (last count bytes). Multiple ranges in one request are not supported. An unsatisfiable range returns 416 with a Content-Range: bytes */total header.

Status Codes

Code	Meaning
`200`	Full content.
`206`	Partial content (range request).
`304`	Not modified (conditional request).
`400`	Wrong or missing `capability`, `map_version`, or file selector — including an unknown `content_id` and an ambiguous or unknown country selector. Body: `Bad Request. Wrong/Missing download filename`.
`404`	The requested version does not exist, or the requested file path does not exist in that version. Body: `File Not Found !`
`416`	Range not satisfiable.

Custom Map Catalogs

Accounts provisioned with a custom map catalog are automatically served from that catalog by all three endpoints — no extra parameter needed. To access the standard Magic Lane catalog from such an account, pass map_type=standard with any request. Accounts without a custom catalog always receive the standard catalog.

No Mixing of Catalogs

Custom maps and standard maps cannot be mixed on a device. Provision all offline content — basemap and regional maps — from a single catalog.

For general information about authentication and API keys, see the Introduction.

Authentication​

Common Parameters​

Versions​

Example Request​

Response​

Status Codes​

File List​

Example Request​

Response​

Status Codes​

Download​

File Selectors​

Example Requests​

Response Headers​

Conditional Requests​

Range Requests​

Status Codes​

Custom Map Catalogs​

Related Documentation​

Authentication

Common Parameters

Versions

Example Request

Response

Status Codes

File List

Example Request

Response

Status Codes

Download

File Selectors

Example Requests

Response Headers

Conditional Requests

Range Requests

Status Codes

Custom Map Catalogs

Related Documentation