# Offline Maps API

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 8 minutes read

<br />

<br />

[v](/docs/cloud-rest-api/guides/maps-3dscene/CHANGELOG/)

<!-- -->

[1.0.0 Release notes →](/docs/cloud-rest-api/guides/maps-3dscene/CHANGELOG/)

<br />

<br />

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[​](#authentication "Direct link to 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[​](#common-parameters "Direct link to 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[​](#versions "Direct link to Versions")

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

**Endpoint:** `GET /offline_maps/versions`

### Example Request[​](#example-request "Direct link to Example Request")

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

```

### Response[​](#response "Direct link to Response")

```json
{
  "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[​](#status-codes "Direct link to 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[​](#file-list "Direct link to 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[​](#example-request-1 "Direct link to Example Request")

```bash
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[​](#response-1 "Direct link to Response")

```json
{
  "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[​](#status-codes-1 "Direct link to 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[​](#download "Direct link to 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[​](#file-selectors "Direct link to 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[​](#example-requests "Direct link to Example Requests")

**Download the world basemap:**

```bash
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):**

```bash
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:**

```bash
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:**

```bash
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[​](#response-headers "Direct link to 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[​](#conditional-requests "Direct link to 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[​](#range-requests "Direct link to 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[​](#status-codes-2 "Direct link to 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[​](#custom-map-catalogs "Direct link to 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.

## Related Documentation[​](#related-documentation "Direct link to Related Documentation")

For general information about authentication and API keys, see the [Introduction](/docs/cloud-rest-api/guides/introduction.md).
