Documentation / Custom basemap and style API

Custom basemap and style API

Configure vector basemap layers, colors, label typography, and fonts using semantic manifests compiled to MapLibre styles.

On this page

Compile a custom basemap style

Use /basemap/contract to retrieve layer identifiers and supported properties. Semantic keys include roads.motorway, landuse.park, and labels.city. The namespace covers background, land use, water, buildings, transit, roads, boundaries, and labels.

Choose a preset from GET /styles. POST a complete manifest or a preset and patch to /styles/compile. The response includes the compiled style, a bundle hash, validation results, and a property diff. Compilation does not save a profile.

curl --fail-with-body https://api.mapsource.io/basemap/contract

curl --fail-with-body https://api.mapsource.io/styles

# Compile a patch against a preset and read the diff
curl --fail-with-body -X POST https://api.mapsource.io/styles/compile \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" -H 'content-type: application/json' -d '{
  "base": "dark",
  "patch": {
    "tokens": { "artery": "#f2a900" },
    "typography": { "labels.city": ["Noto Sans Bold", "Noto Sans Regular"] },
    "layers": {
      "roads.motorway": { "color": "$artery", "casingColor": "#111111",
                          "width": [[6, 1.1], [12, 3.6], [18, 13]] },
      "labels.poi": { "minzoom": 16 }
    }
  }
}'

Endpoints and parameters

Select an endpoint for its full parameter and response reference.

Operation	Endpoint
Read the semantic basemap layer namespace	`GET /api/basemap/contract`
Read the semantic style JSON Schema	`GET /api/styles/schema.json`
Compile a style manifest	`POST /api/styles/compile`
Save a basemap profile	`POST /api/styles/profiles`
List a profile's immutable revisions	`GET /api/styles/{id}/revisions`
Compare two revisions at the semantic level	`GET /api/styles/{id}/diff`
Upload a font	`POST /api/fonts`
Render a static map	`POST /api/render/static`

Application integration

Read the semantic layer definitions, select a base preset, and submit a patch for compilation. Review validation issues and the returned diff before saving the manifest as a profile.

Load the compiled style URL in MapLibre and attach a Bearer header to authenticated tile and profile requests. Use a revision-specific style URL when a fixed profile version is required.

Inspect font coverage before assigning a custom font to multilingual labels. Keep source attribution visible in interactive maps and static exports.

Access and limits

Widths and text sizes accept constants or zoom curves in the form [[zoom, value], ...]. Colors accept literals and $token palette references. Unresolved tokens and invalid zoom ranges return HTTP 422. Unknown semantic keys produce warnings.

Hosted preset styles and glyph ranges are public. Vector tiles require authentication. Saved profiles and custom fonts are scoped to the owning key; configure authentication for their requests without placing credentials in URLs.

Upload TTF, OTF, or WOFF fonts as base64 data to POST /fonts. The response lists available faces and Unicode coverage. Each key supports up to 12 fonts, with a maximum size of 12 MB per font, and up to 50 saved style profiles.

See plan limits for request allowances and error handling for quota and retry behavior.

Responses and examples

Compilation returns a MapLibre style, bundle hash, validation issues, and semantic-to-render-layer mappings. Save a manifest with POST /styles/profiles to retrieve it later by slug. Use /styles/{slug}/style.json for the compiled style and /styles/{slug}/manifest.json for the manifest; add ?download=1 to download either document.

Pass a profile slug as style to POST /render/static for server-side rendering. The quickstart basemap editor supports previewing, saving, and downloading profiles.

Example responses and timing measurements · Current service status

Attribution

Compiled styles carry OpenMapTiles and OpenStreetMap attribution in the source definition. Keep it visible when you render or export the style.

Source and reference · Mapsource attribution guide

Questions about this guide? Contact support.