Developer documentation

MapAPlace API

Connect server-side applications to create, read, update, publish, and delete maps using scoped API credentials.

Overview

The custom API uses the OAuth 2.0 client-credentials flow. Your integration exchanges its API key and one-time API secret for an opaque Bearer token, then sends that token to the map API.

Use a trusted server

Never put the API secret or token exchange in browser JavaScript, a mobile application bundle, a public repository, a URL, or client-visible map data. A backend, serverless function, or other confidential server process should own the credentials.

  1. Create a credential in Settings → API integrations.
  2. Store the API key and secret in your server’s secret store.
  3. Exchange them for a one-hour Bearer token.
  4. Call map endpoints with both the Bearer token and exact configured Origin.
  5. Request a new token when the current token expires. There is no refresh token.

Create a credential

Open Settings → API integrations and select Create new API credential. Your current password confirms this security-sensitive action.

FieldMeaning
NameA recognizable label for the integration. It is not sent with API requests.
Website URLThe exact HTTPS origin that every token and protected API request must carry, for example https://integration.example. Paths and credentials are removed; local development may use HTTP only for localhost or loopback addresses.
PermissionsThe maximum scopes any token created from this credential may receive.
Allow admin rightsAllows the connection to change enabled map modules and connected-website settings. It does not make the account user a MapAPlace administrator.

The API secret is displayed once. Copy it immediately. MapAPlace stores only a cryptographic digest and cannot show the original secret later. If it is lost or exposed, delete the integration and create a new credential.

Deleting a credential immediately revokes its active tokens. Use a separate credential for every external system so one integration can be revoked without interrupting another.

Get an access token

Send HTTP Basic credentials to POST /api/v1/oauth/token. The username is the API key and the password is the API secret. The body must use application/x-www-form-urlencoded with grant_type=client_credentials.

Token request cURL
export MAPAPLACE_URL="https://mapaplace.com"
export MAPAPLACE_ORIGIN="https://your-integration.example"
export MAPAPLACE_API_KEY="api-key_..."
export MAPAPLACE_API_SECRET="your-one-time-secret"

curl --request POST "$MAPAPLACE_URL/api/v1/oauth/token" \
  --user "$MAPAPLACE_API_KEY:$MAPAPLACE_API_SECRET" \
  --header "Origin: $MAPAPLACE_ORIGIN" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=maps:read maps:write"

Omit scope to receive every scope assigned to the credential, or supply a space-separated subset. Asking for an unassigned scope fails without revealing credential details.

Successful token response JSON
{
  "access_token": "opaque-256-bit-token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "maps:read maps:write"
}
Token request from Node.js JavaScript
const mapAPlaceUrl = "https://mapaplace.com";
const integrationOrigin = "https://your-integration.example";
const apiKey = process.env.MAPAPLACE_API_KEY;
const apiSecret = process.env.MAPAPLACE_API_SECRET;

const basic = Buffer.from(apiKey + ":" + apiSecret, "utf8").toString("base64");
const body = new URLSearchParams({
  grant_type: "client_credentials",
  scope: "maps:read maps:write",
});
const response = await fetch(mapAPlaceUrl + "/api/v1/oauth/token", {
  method: "POST",
  headers: {
    Authorization: "Basic " + basic,
    "Content-Type": "application/x-www-form-urlencoded",
    Origin: integrationOrigin,
  },
  body,
});
if (!response.ok) throw new Error("Token request failed: " + response.status);
const token = await response.json();

Tokens expire after 3,600 seconds. Cache a token server-side until shortly before expiry, then perform another client-credentials exchange.

Make authenticated requests

Every protected request needs both headers below. The Origin must exactly equal the credential’s Website URL origin, including scheme and any non-default port.

  • Authorization: Bearer <access-token>
  • Origin: https://your-integration.example
List maps cURL
curl "$MAPAPLACE_URL/api/v1/maps?page=1" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN"
List response JSON
{
  "maps": [
    {
      "id": "map_time_entropy",
      "slug": "map_time_entropy",
      "title": "Visitor map",
      "status": "published",
      "hasSavedRevision": true,
      "hasUnpublishedChanges": false,
      "embedAllowedOrigin": "https://www.example.com",
      "embedAllowedOriginReadOnly": false,
      "accessLevel": "owner",
      "createdAt": "2026-07-21T12:00:00.000Z",
      "updatedAt": "2026-07-21T12:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 1,
    "totalPages": 1
  }
}

Map resources are always restricted to the account user who owns the credential. Knowing another map ID does not grant access.

Browser requests: the confidential API is intended for server-side integrations. Do not work around browser restrictions or proxy the API key and secret into frontend code. Your backend can expose its own narrow, authenticated endpoint to your frontend when needed.

Scopes and admin rights

maps:read

List maps and read map metadata, drafts, published artifacts, and specific revisions.

maps:write

Create map records, save immutable revisions, and upload image assets.

maps:publish

Publish, unpublish, and change the map’s allowed embed origin.

maps:delete

Soft-delete maps owned by the connected account user.

Admin rights are separate from scopes. Without admin rights, a saved revision can change normal map content but MapAPlace preserves the current enabled/disabled module state and other connection-restricted settings. Enable admin rights only for a trusted integration that must manage those settings.

Map endpoints

Use the MapAPlace origin shown beside the generated credential as the base URL. Protected management responses use Cache-Control: no-store.

MethodPathScopePurpose
GET /api/v1/maps?page={page} maps:read List accessible maps in pages of 10.
POST /api/v1/maps maps:write Create an empty owned map with a title.
GET /api/v1/maps/{mapId} maps:read Read safe map metadata.
DELETE /api/v1/maps/{mapId} maps:delete Soft-delete a map. Only an owner can delete it.
PUT /api/v1/maps/{mapId}/embed-policy maps:publish Allow one exact HTTPS origin to embed the published viewer.
PUT /api/v1/maps/{mapId}/public-access maps:publish Enable, change, or remove password protection for public delivery.
POST /api/v1/maps/{mapId}/revisions maps:write Validate and store a complete immutable map artifact.
GET /api/v1/maps/{mapId}/draft/map.json maps:read Read the current draft artifact.
GET /api/v1/maps/{mapId}/published/map.json maps:read Read the current published artifact for the account.
GET /api/v1/maps/{mapId}/revisions/{revisionId}/map.json maps:read Read a specific accessible revision artifact.
POST /api/v1/maps/{mapId}/publish maps:publish Publish the current draft revision.
POST /api/v1/maps/{mapId}/unpublish maps:publish Remove the map from public delivery without deleting its draft.

Create a map

Create an empty map record cURL
curl --request POST "$MAPAPLACE_URL/api/v1/maps" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN" \
  --header "Content-Type: application/json" \
  --data '{"title":"Visitor map"}'

The response is 201 Created with { "map": { ... } }. The returned map.id is used in later requests. A newly created map has no saved revision until you upload an artifact.

Save a revision

Upload a complete revision cURL
curl --request POST \
  "$MAPAPLACE_URL/api/v1/maps/map_time_entropy/revisions" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN" \
  --header "Content-Type: application/json" \
  --data @revision-request.json
revision-request.json JSON
{
  "title": "Visitor map",
  "artifact": {
    "format": "mapaplace-map",
    "formatVersion": 1,
    "revisionId": "revision_time_entropy",
    "encoding": "gzip+base64url",
    "compressedBytes": 312,
    "uncompressedBytes": 540,
    "checksum": "sha256:64-lowercase-hex-characters",
    "payload": "base64url-encoded-gzip-data"
  }
}

Revisions are immutable. Every save needs a new valid revisionId. Reusing a revision ID returns 409 Revision already exists. The route validates the artifact, checksum, map identity, schema, canonical JSON, compressed sizes, and extension limits before storage.

Map artifact contract

Draft, published, and historical map.json endpoints return an encoded artifact. The payload is URL-safe base64 without padding containing a gzip-compressed, canonical UTF-8 JSON document. checksum is the SHA-256 digest of the uncompressed document bytes.

To update an existing map, fetch its draft artifact, decode and decompress the payload, update the document through a compatible MapAPlace client, then create a new canonical artifact and revision ID. Do not edit only the outer metadata or reuse a checksum.

Core map document before canonical encoding JSON
{
  "baseMap": {
    "providerId": "openfreemap-liberty",
    "showBuildings": true,
    "show3dBuildings": false,
    "showPois": true
  },
  "camera": {
    "longitude": -0.1276,
    "latitude": 51.5072,
    "zoom": 11,
    "pitch": 0,
    "bearing": 0
  },
  "controls": {
    "zoom": true,
    "fullscreen": true,
    "distanceScale": true
  }
}
Minimal artifact encoder for Node.js JavaScript
import { createHash, randomUUID } from "node:crypto";
import { gzipSync } from "node:zlib";

function createMapAPlaceId(prefix) {
  const timestamp = Date.now().toString(36).padStart(9, "0");
  const entropy = randomUUID().replaceAll("-", "").toLowerCase();
  return prefix + "_" + timestamp + "_" + entropy;
}

function canonicalize(value) {
  if (Array.isArray(value)) return value.map(canonicalize);
  if (value && typeof value === "object") {
    return Object.fromEntries(
      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
    );
  }
  return value;
}

function createMapArtifact(mapId, coreDocument, extensions = {}) {
  const document = canonicalize({
    ...coreDocument,
    extensions,
    mapId,
    schemaVersion: 1,
  });
  const uncompressed = Buffer.from(JSON.stringify(document), "utf8");
  const compressed = gzipSync(uncompressed);
  return {
    format: "mapaplace-map",
    formatVersion: 1,
    revisionId: createMapAPlaceId("revision"),
    encoding: "gzip+base64url",
    compressedBytes: compressed.byteLength,
    uncompressedBytes: uncompressed.byteLength,
    checksum: "sha256:" + createHash("sha256").update(uncompressed).digest("hex"),
    payload: compressed.toString("base64url"),
  };
}

The helper shows the version 1 envelope and identifier algorithm. Validate application input before passing it to the helper; the MapAPlace server remains authoritative and rejects documents outside the contract.

Core document rules

  • schemaVersion is currently 1 and is added during artifact creation.
  • Longitude is −180 to 180, latitude is −90 to 90, zoom is 0 to 24, pitch is 0 to 85, and bearing is −180 to 180.
  • Optional camera bounds require explicit boundsEnabled and southwest/northeast values.
  • All control and base-map feature switches are explicit booleans.
  • extensions is an object keyed by installed module ID. Extension schemas and required premium access remain module-specific.
  • The uncompressed document limit is 512 KiB. Unknown fields, unsafe keys, invalid numbers, and non-canonical key ordering are rejected.

Routing provider credentials are never accepted inside a map artifact; use the map editor’s protected credential controls for those secrets.

Publish and embed

Publish the current draft cURL
curl --request POST \
  "$MAPAPLACE_URL/api/v1/maps/map_time_entropy/publish" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN"
Allow one website to embed the viewer cURL
curl --request PUT \
  "$MAPAPLACE_URL/api/v1/maps/map_time_entropy/embed-policy" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN" \
  --header "Content-Type: application/json" \
  --data '{"allowedOrigin":"https://www.example.com"}'
Public URLPurpose
GET /api/v1/public/maps/{slug}Public title and status metadata for a published map.
GET /api/v1/public/maps/{slug}/map.jsonThe current published artifact. Supports ETag and If-None-Match.
POST /api/v1/public/maps/{slug}/accessExchange the map password for a short-lived map access token.
GET /maps/{slug}Standalone public map viewer.
GET /embed/maps/{slug}Embeddable viewer, restricted to the configured embed-policy origin.

Unprotected public artifact responses may be cached for 15 minutes and can use stale content during a temporary error. Password-protected responses are private and are not cached. Drafts, revision history, and account metadata are never exposed by public routes. Unpublishing immediately removes the public map routes and viewer.

Image assets

Upload raw JPEG, PNG, SVG, or WebP bytes with maps:write. Files must be no larger than 5 MiB and no wider or taller than 4,096 pixels. MapAPlace validates and normalizes the image to managed WebP.

Upload an image cURL
curl --request POST "$MAPAPLACE_URL/api/v1/assets/images" \
  --header "Authorization: Bearer $MAPAPLACE_ACCESS_TOKEN" \
  --header "Origin: $MAPAPLACE_ORIGIN" \
  --header "Content-Type: image/png" \
  --data-binary @marker.png

A successful 201 response contains the asset ID, final MIME type, dimensions, checksum, creation time, and previewUrl. Metadata is available from GET /api/v1/assets/{assetId}; normalized bytes are available from GET /api/v1/assets/{assetId}/preview.

Errors, status codes, and limits

Most failures return JSON with one safe error message:

Error response JSON
{
  "error": "Insufficient scope"
}
StatusMeaning
400Invalid body, pagination, origin, map artifact, or field value.
401Missing, invalid, expired, revoked, or wrong-origin credentials/token.
403The token lacks the required scope.
404The resource is missing or is not accessible to this credential’s user.
409The revision ID already exists.
429Rate limit exceeded. Respect Retry-After and retry with backoff.
500An internal storage or processing operation failed.

Current rate limits

  • Token exchange: 20 requests per minute.
  • Map reads and listings: 300 requests per minute.
  • Map creation and revision writes: 60 requests per minute.
  • Publish, unpublish, embed-policy, public-access, and delete operations: 20 to 30 requests per minute.
  • Map password attempts: 10 requests per minute.
  • Public map delivery: 600 requests per minute.

Security checklist

  • Use HTTPS in production and verify TLS certificates.
  • Keep the API secret and access tokens in a server-side secret store.
  • Create one credential per integration and grant only required scopes.
  • Leave admin rights disabled unless module and connected-site settings must be changed.
  • Send the exact configured Origin on token and Bearer requests.
  • Do not log Authorization headers, API secrets, Bearer tokens, or complete credential responses.
  • Delete a credential immediately if it is exposed or no longer used.
  • Treat all IDs as opaque strings and all API responses as untrusted input requiring normal error handling.