API reference

Reference for 60 API operations, including authentication, parameters, limits, and error codes.

On this page

Using the API

Send requests to https://api.mapsource.io; paths below are relative to it. Each also works with an /api prefix, the form https://mapsource.io serves. Authenticated endpoints require an Authorization: Bearer $MAPSOURCE_API_KEY header. Parameters marked with an asterisk are required. See the OpenAPI specification for REST schemas and the MCP guide for agent integration.

Each operation lists its access requirements and resource limits. Quota weight is a relative operation cost; see request accounting for monthly usage. Deterministic operations produce consistent results for unchanged inputs and data versions; this does not make repeated writes or payments safe. Follow the retry guidance for failures.

Engine version. The currently deployed Overpass engine version is published by GET /api/status; see overpass.displayVersion. It identifies the engine build currently serving Mapsource requests and changes automatically when production is upgraded. The datasets array reports the same for every other dataset: the engine build serving it and the data snapshot it answers from, each read from the backend itself.

Pass result handles between supported operations to process large datasets without downloading intermediate geometry.

Discovery and query

Execute an Overpass QL query

POST / GET /interpreter

Queries OpenStreetMap nodes, ways, relations, and generated areas. Supports tags, spatial filters, sets, recursion, geometry, metadata, and JSON, XML, or CSV output.

Operation id: queryOverpass
Access: Subscription key or x402 payment
Quota weight: 5
Latency class: slow
Deterministic: No
Agent tool: geo_search operation overpass
Produces a handle: feature_collection

Usage Query arbitrary OSM tags, spatial relationships, or topology using Overpass QL.

Considerations Use lookupPlaces for address and business suggestions, discoverPlaces for regional POI lists, or findNearby for category-based radius searches.

Parameter	Location	Type	Constraints	Description
`data` *	body	string	max length 131072	A complete bounded QL program.

Operation-specific errors QUERY_TOO_LARGE, TIMEOUT_EXCEEDS_PLAN, MAXSIZE_EXCEEDS_PLAN, ATTIC_UNSUPPORTED, RESPONSE_TOO_LARGE

Response headers X-Mapsource-Overpass-Version, X-Mapsource-Overpass-Commit, X-Mapsource-Gateway-Version, X-Mapsource-Gateway-Commit

Execute Overpass QL with the key in the path

POST / GET /{key}/interpreter

Overpass interpreter access with a credential in the URL path. Query behavior, limits, quota, and errors match /api/interpreter.

Operation id: queryOverpassCompat
Access: Subscription key
Quota weight: 5
Latency class: slow
Deterministic: No
Produces a handle: feature_collection

Usage Connect existing Overpass clients that cannot set request headers.

Considerations Prefer Bearer authentication. URL credentials may appear in logs, browser history, and referrer headers.

Parameter	Location	Type	Constraints	Description
`key` *	path	string	—	The subscription key. Prefer the Authorization header wherever the client allows one.
`data` *	body	string	max length 131072	A complete bounded QL program.

Operation-specific errors QUERY_TOO_LARGE, TIMEOUT_EXCEEDS_PLAN, MAXSIZE_EXCEEDS_PLAN, ATTIC_UNSUPPORTED, RESPONSE_TOO_LARGE

Response headers X-Mapsource-Overpass-Version, X-Mapsource-Overpass-Commit, X-Mapsource-Gateway-Version, X-Mapsource-Gateway-Commit

Resolve a name to a geographic entity

GET /entities/resolve

Resolves a place name to an entity ID, type, display name, center, source ID, and confidence score. Similar-scoring candidates produce an ambiguous result.

Operation id: resolveEntity
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_search operation resolve

Usage Resolve a place once and reference its entity ID in subsequent operations.

Considerations Use nearby search for features around a point, or readEntity for an existing entity ID.

Parameter	Location	Type	Constraints	Description
`q` *	query	string	min length 1, max length 120	The place name.
`lat`	query	number	min -85.05112878, max 85.05112878	Bias toward this latitude without hiding distant matches.
`lon`	query	number	min -180, max 180	Bias toward this longitude.
`limit`	query	integer	min 1, max 50, default 10	Maximum number of candidates.

Read an entity by its id

GET /entities/{entityId}

Retrieves an entity from the current dataset using the source reference encoded in its ID.

Operation id: readEntity
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_search operation entity

Usage Retrieve the name, center, and bounding box associated with an entity ID.

Parameter	Location	Type	Constraints	Description
`entityId` *	path	string	—	An id from resolveEntity, beginning geo_.

Operation-specific errors NOT_FOUND

Resolve a place name to a coordinate

GET /places/search

Global place-name search over a locally built index, ranked by prominence with an optional bias point.

Operation id: searchPlaces
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_search operation search
Produces a handle: place_collection

Usage Look up a populated place by name and retrieve its coordinates.

Considerations Use lookupPlaces for addresses, businesses, brands and mixed destination suggestions. Use discoverPlaces for businesses within a viewport, polygon or travel-time region.

Parameter	Location	Type	Constraints	Description
`q` *	query	string	max length 120	Place name to look up.
`limit`	query	integer	min 1, max 50, default 10	Maximum results.
`lat`	query	number	min -85.05112878, max 85.05112878	Bias results toward this point without excluding distant matches.
`lon`	query	number	min -180, max 180	Bias results toward this point without excluding distant matches.
`class`	query	string	one of city, town, village, suburb, neighbourhood, hamlet	Restrict to one class of populated place.

Look up addresses, businesses and places

GET /places/lookup

Local OSM address/name lookup for map search and routing destination pickers. Supports business categories, partial names, accent normalization and typo matching. Coordinates bias ranking; bounded=true is required to restrict results to bbox. When the global index is unavailable, coverage identifies the regional Overpass and place-name-index fallback. Included in every subscription plan: one successful lookup counts as one request, plus an interpreter request if regional Overpass fallback is used. Search index freshness is independent of the Overpass dataset; read coverage.dataTimestamp.

Operation id: lookupPlaces
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: No
Agent tool: geo_search operation lookup

Usage Find an address, business, brand, landmark, street or populated place. Use a location qualifier such as Starbucks in Portland to search away from the map focus.

Considerations Use discoverPlaces to enumerate businesses in a viewport or travel-time region. Ranking scores are not probabilities; bestMatchId is null for ambiguous matches. House numbers are never substituted.

Parameter	Location	Type	Constraints	Description
`q` *	query	string	min length 1, max length 120	Search text; addresses retain the requested house number.
`lat`	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon`	query	number	min -180, max 180	Longitude in decimal degrees.
`limit`	query	integer	min 1, max 20, default 8	Maximum results.
`language`	query	string	default "en"	Preferred language code. Unavailable translations fall back to source names with a warning.
`types`	query	string	—	Comma-separated address,business,landmark,street,place filters.
`category`	query	string	—	Business/POI category or alias, such as coffee, pharmacy, restaurants, groceries, hotels, shops or parks.
`countrycodes`	query	string	—	Comma-separated two-letter country codes. Records without a source country code do not satisfy this filter.
`bbox`	query	string	—	west,south,east,north. A focus hint unless bounded=true; no dateline crossing.
`bounded`	query	boolean	default false	Restrict results to bbox. A bias point alone never requests this restriction.

Find businesses and POIs in a region

POST /places/discover

Select OSM shops, offices, amenities and visitor facilities inside a viewport, polygon or travel-time region. Uses the local Overpass database, polygon filtering and, optionally, Valhalla. No geocoder index is required. Each internal Overpass, isochrone or matrix request consumes its normal quota; the composition adds no separate request charge.

Operation id: discoverPlaces
Access: Subscription key
Quota weight: free
Latency class: slow
Deterministic: No
Agent tool: geo_search operation discover
Accepts handles: isochrone, analysis, feature_collection

Usage Find coffee within a 15-minute drive, list businesses in a map viewport, or filter POIs by an existing isochrone. Paginate bounded results; narrow the area when coverage.truncated is true.

Considerations Use lookupPlaces for ranked address/name suggestions. Discovery uses feature centers, not full-geometry intersections. It does not guarantee a complete real-world business directory: only mapped OSM records are available. Travel-time ranking compares at most the 25 nearest candidates.

Parameter	Location	Type	Constraints	Description
`q`	body	string	max length 120	Optional business name or brand filter.
`category`	body	string	—	Optional category alias, such as coffee, pharmacy, restaurants, hotels or shops.
`bbox`	body	string	—	west,south,east,north (a four-number array is also accepted). Maximum extent: one degree per axis. Supply exactly one of bbox, region or minutes.
`region`	body	object	—	GeoJSON Polygon, MultiPolygon, polygon Feature/FeatureCollection, or an owned result-handle ID. Closed rings required; holes excluded. Maximum encoded coordinates: 100 KB.
`minutes`	body	integer	min 1, max 30	Generate a reachable region from lat/lon.
`lat`	body	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon`	body	number	min -180, max 180	Longitude in decimal degrees.
`costing`	body	string	one of auto, bicycle, pedestrian, truck, default "auto"	Travel mode for isochrone and matrix requests.
`rankBy`	body	string	one of distance, travel_time, default "distance"	distance sorts from lat/lon or the region center. travel_time requires lat/lon, limit <=25 and offset=0; unreachable times remain null.
`limit`	body	integer	min 1, max 100, default 20	Page size.
`offset`	body	integer	min 0, max 2000, default 0	Offset into the bounded candidate results; re-query after dataset updates may change ordering.
`language`	body	string	default "en"	Preferred source name language.

Operation-specific errors UPSTREAM_UNAVAILABLE, HANDLE_EXPIRED

Prefix-match a place name

GET /places/autocomplete

Prefix search over the place-name index, matching the final word of a partial query.

Operation id: autocompletePlaces
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_search operation autocomplete
Produces a handle: place_collection

Usage Provide place-name suggestions as a user types.

Considerations Use lookupPlaces for address, business and brand suggestions, including partial names. Use searchPlaces for complete populated-place names.

Parameter	Location	Type	Constraints	Description
`q` *	query	string	max length 120	Partial place name.
`limit`	query	integer	min 1, max 50, default 10	Maximum results.
`lat`	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon`	query	number	min -180, max 180	Longitude in decimal degrees.

Find features within a radius

GET /places/nearby

Returns named features or category matches within a radius, sorted by distance.

Operation id: findNearby
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: No
Agent tool: geo_search operation nearby
Produces a handle: place_collection

Usage Find nearby amenities, infrastructure, or named features around a coordinate.

Considerations Use Overpass QL for bounding-box queries or areas beyond the supported radius.

Parameter	Location	Type	Constraints	Description
`lat` *	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon` *	query	number	min -180, max 180	Longitude in decimal degrees.
`radius`	query	integer	min 10, max 5000, default 500	Metres.
`category`	query	string	—	Omit for any named feature.
`limit`	query	integer	min 1, max 100, default 20	Maximum records.

Reverse geocode a coordinate

GET /places/reverse

Reverse geocodes against the local Photon address index and returns the nearest indexed house number, street, district, city, state, postcode, country and country code with coordinate, distance and OSM identity. Local Overpass candidates remain available as traceable fallbacks.

Operation id: reverseGeocode
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: No
Agent tool: geo_search operation reverse

Usage Retrieve a complete locally indexed postal address or place identity associated with a coordinate.

Parameter	Location	Type	Constraints	Description
`lat` *	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon` *	query	number	min -180, max 180	Longitude in decimal degrees.
`radius`	query	integer	min 10, max 1000, default 150	Metres.

Read one feature by its OSM identity

GET /places/{osmType}/{osmId}

Returns the tags and geometry center of an OSM node, way, or relation.

Operation id: readPlace
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: No
Agent tool: geo_search operation details

Usage Retrieve details for an OSM object identified by type and ID.

Parameter	Location	Type	Constraints	Description
`osmType` *	path	string	one of node, way, relation	node, way or relation.
`osmId` *	path	integer	min 1	Positive OSM id.

Operation-specific errors NOT_FOUND

Geocode through the compatibility provider

GET /geocode

Address and place lookup through the separately configured, rate-limited geocoding provider. Retained for clients using this response format; local search is available through lookupPlaces.

Operation id: forwardGeocode
Access: Subscription key
Quota weight: 2
Latency class: slow
Deterministic: No
Agent tool: geo_search operation geocode

Usage Maintain an existing integration that requires the compatibility geocoder's response format.

Considerations Use lookupPlaces for new address, business, brand and place search integrations. This provider-backed endpoint supports interactive requests, not bulk geocoding.

Parameter	Location	Type	Constraints	Description
`q` *	query	string	max length 200	Address or place text.

Execute an Overpass query with x402

POST /x402/interpreter

Executes a bounded JSON-output Overpass QL query using per-request x402 payment.

Operation id: paidOverpassQuery
Access: Subscription key or x402 payment
Quota weight: 5
Latency class: slow
Deterministic: No

Usage Submit a query using an authorized compatible wallet without a subscription key.

Considerations Use the subscription interpreter when an API key is available. Query payments do not include tiles or elevation.

Parameter	Location	Type	Constraints	Description
`query` *	body	string	min length 1, max length 131072	Overpass QL using [out:json]. Send a JSON object with this field.

Operation-specific errors PAYMENT_REQUIRED, QUERY_TOO_LARGE, RESPONSE_TOO_LARGE

Spatial compute and handles

Run a spatial analysis

POST /analyze

Buffer, centroid, bbox, area, length, distance, intersect, union, difference, contains, intersects, nearest, simplify and convex hull.

Operation id: analyzeGeometry
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: Yes
Agent tool: geo_analyze operation analyze
Accepts handles: feature_collection, route, isochrone, analysis, place_collection
Produces a handle: analysis

Usage Measure or transform GeoJSON, coordinates, query results, and result handles.

Considerations Use a pipeline for several dependent operations in one request.

Parameter	Location	Type	Constraints	Description
`operation` *	body	string	one of buffer, centroid, bbox, area, length, distance, intersect, union, difference, contains, intersects, nearest, simplify, convex	The operation to run.
`a` *	body	object	—	GeoJSON, a [lon, lat] pair, a query or places result, or a result handle.
`b`	body	object	—	Second operand, in the same forms as a.
`distance`	body	number	min 0, max 500000	Buffer radius or simplify tolerance.
`units`	body	string	one of meters, kilometers, miles, default "meters"	Units for distance.

Run a multi-step spatial pipeline

POST /compute

Executes up to 12 ordered steps with references to earlier results and returns the selected output.

Operation id: runPipeline
Access: Subscription key
Quota weight: 10
Latency class: batch
Deterministic: No
Agent tool: geo_analyze operation pipeline
Accepts handles: feature_collection, route, isochrone, matrix, analysis, place_collection
Produces a handle: analysis

Usage Run dependent search, navigation, and analysis without downloading intermediate results.

Considerations Call the relevant endpoint directly for a single operation.

Parameter	Location	Type	Constraints	Description
`pipeline` *	body	array	min 1, max 12	Ordered steps of {id, op, args}.
`return`	body	string	—	Which step to return, as $stepId. Defaults to the last.
`estimateOnly`	body	boolean	default false	Report the cost without executing.

Operation-specific errors PIPELINE_INVALID, PIPELINE_STEP_FAILED, PIPELINE_DEADLINE_EXCEEDED, HANDLE_EXPIRED, HANDLE_QUOTA_EXCEEDED

Retrieve a held result

GET /results/{id}

Retrieves a result payload or its metadata: type, version, feature count, size, bounding box, dataset versions, operation hash, and lineage.

Operation id: readResult
Access: Subscription key
Quota weight: 1
Latency class: instant
Deterministic: Yes
Agent tool: geo_analyze operation result

Usage Download a result payload or inspect its metadata before further processing.

Considerations Pass the handle directly to supported operations when the client does not need the payload.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	The handle id, rh_ followed by 32 hex characters.
`mode`	query	string	one of summary	summary returns the envelope without the payload.

Operation-specific errors HANDLE_EXPIRED, NOT_FOUND

Routing and navigation

Compute a turn-by-turn route

POST /route

A route between 2 and 10 waypoints on the global road graph, optionally with a sampled elevation profile.

Operation id: computeRoute
Access: Subscription key
Quota weight: 3
Latency class: fast
Deterministic: No
Agent tool: geo_navigate operation route
Accepts handles: place_collection
Produces a handle: route

Usage Retrieve route geometry, directions, distance, and travel time between waypoints.

Considerations Use a matrix for travel-time comparisons across multiple origins and destinations.

Parameter	Location	Type	Constraints	Description
`locations` *	body	array	min 2, max 10	Ordered waypoints; first is origin, last is destination.
`costing`	body	string	one of auto, bicycle, pedestrian, truck, motor_scooter, bus, default "auto"	Travel mode.
`elevation`	body	boolean	default false	Also return a terrain profile with gain and loss.

Compute a travel-time and distance matrix

POST /matrix

Returns travel times and distances for up to 625 origin-destination pairs per request.

Operation id: computeMatrix
Access: Subscription key
Quota weight: 8
Latency class: slow
Deterministic: No
Agent tool: geo_navigate operation matrix
Accepts handles: place_collection, feature_collection
Produces a handle: matrix

Usage Compare destinations or build a travel-time matrix for analysis.

Considerations Use route when directions or route geometry are required.

Parameter	Location	Type	Constraints	Description
`sources` *	body	array	min 1, max 25	Origins.
`targets`	body	array	max 25	Destinations. Omit for the square matrix of sources against themselves.
`costing`	body	string	one of auto, bicycle, pedestrian, truck, motor_scooter, bus, default "auto"	Travel mode.

Compute reachable-area polygons

POST /isochrone

Returns reachable-area polygons for up to four travel-time bands from one origin.

Operation id: computeIsochrone
Access: Subscription key
Quota weight: 6
Latency class: slow
Deterministic: No
Agent tool: geo_navigate operation isochrone
Produces a handle: isochrone

Usage Calculate service areas, catchments, or accessibility within a travel-time limit.

Parameter	Location	Type	Constraints	Description
`entity`	body	string	—	An entity id to centre on, instead of lat and lon.
`lat` *	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon` *	query	number	min -180, max 180	Longitude in decimal degrees.
`costing`	body	string	one of auto, bicycle, pedestrian, truck, motor_scooter, bus, default "auto"	Travel mode.
`contours`	body	array	min 1, max 4	Travel-time bands in minutes.

Fit a GPS trace to the road network

POST /map-match

Returns matched geometry, confidence scores, and OSM way IDs for an ordered GPS trace.

Operation id: matchTrace
Access: Subscription key
Quota weight: 5
Latency class: slow
Deterministic: No
Agent tool: geo_navigate operation map_match
Produces a handle: route

Usage Match recorded travel coordinates to the road network.

Parameter	Location	Type	Constraints	Description
`shape` *	body	array	min 2, max 1000	The trace, in order.
`costing`	body	string	default "auto"	Travel mode.
`shapeMatch`	body	string	one of map_snap, edge_walk, default "map_snap"	map_snap tolerates noise; edge_walk assumes the trace already follows the network.

Snap points to the road network

POST /snap

Returns the nearest road-network position for each coordinate, including way ID, street name, and side of street.

Operation id: snapPoints
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: No
Agent tool: geo_navigate operation snap

Usage Associate coordinates with road segments before routing or analysis.

Parameter	Location	Type	Constraints	Description
`locations` *	body	array	min 1, max 50	Points to snap.
`costing`	body	string	default "auto"	Travel mode.

Solve the visit order for a set of stops

POST /optimize

Optimizes the visit order for 3 to 20 stops while keeping the first and last fixed.

Operation id: optimizeOrder
Access: Subscription key
Quota weight: 8
Latency class: slow
Deterministic: No
Agent tool: geo_navigate operation optimize
Produces a handle: route

Usage Plan stop sequences for delivery, fieldwork, or multi-stop travel.

Parameter	Location	Type	Constraints	Description
`locations` *	body	array	min 3, max 20	Stops; first and last are held fixed.
`costing`	body	string	default "auto"	Travel mode.

Terrain and elevation

Sample ground elevation

GET /elevation

Surface height at a coordinate, floored at sea level, with the raw model reading alongside.

Operation id: sampleElevation
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_data operation elevation

Usage Retrieve terrain height and the raw model elevation at one coordinate.

Considerations Use route with elevation enabled for a profile along a route.

Parameter	Location	Type	Constraints	Description
`lat` *	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon` *	query	number	min -180, max 180	Longitude in decimal degrees.

Read a terrarium-encoded elevation tile

GET /terrain/{z}/{x}/{y}.png

Returns a Terrarium-encoded Mapzen Terrain PNG for MapLibre raster-dem sources.

Operation id: getTerrainTile
Access: Subscription key
Quota weight: 1
Latency class: fast
Deterministic: Yes
Agent tool: geo_data operation terrain

Usage Display hillshading or 3D terrain using the catalog's tile template and zoom range.

Considerations Use sampleElevation for a single coordinate without decoding a tile.

Parameter	Location	Type	Constraints	Description
`z` *	path	integer	—	Zoom, 0 to 15.
`x` *	path	integer	—	Tile column.
`y` *	path	integer	—	Tile row, with the .png suffix.

Generate banded topographic contours

GET /contours

Vector contour bands with elevations, index flags and along-band label paths.

Operation id: generateContours
Access: Subscription key
Quota weight: 4
Latency class: slow
Deterministic: Yes
Agent tool: geo_data operation contours
Produces a handle: feature_collection

Usage Display elevation contours or analyze terrain relief around a coordinate.

Parameter	Location	Type	Constraints	Description
`lat` *	query	number	min -85.05112878, max 85.05112878	Latitude in decimal degrees.
`lon` *	query	number	min -180, max 180	Longitude in decimal degrees.
`zoom`	query	integer	min 6, max 13, default 9	Resolution.
`bands`	query	integer	min 4, max 24, default 14	Requested band count.

Semantic cartography

Read the semantic basemap layer namespace

GET /basemap/contract

Semantic layer identifiers, supported style properties, and mappings to the tile schema.

Operation id: readBasemapContract
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation explain

Usage Look up layer identifiers and properties when creating or editing a style.

Considerations Use the basemap catalog to retrieve tile URLs.

No parameters.

List style presets and saved profiles

GET /styles

Lists available presets and profiles associated with the authenticated key.

Operation id: listStyles
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation list

Usage Select a preset or retrieve saved basemap profiles.

No parameters.

Read a compiled MapLibre style

GET /styles/{id}/style.json

The compiled style document for a preset or one of your saved profiles. metadata['mapsource:ui'] contains the resolved colors and font stacks for browser attribution and result labels; install the public Map UI helper to apply them to HTML controls.

Operation id: readCompiledStyle
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes

Usage Load a preset or saved profile into a MapLibre-compatible client.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	Preset id or profile slug.

Operation-specific errors NOT_FOUND

Read the semantic manifest behind a style

GET /styles/{id}/manifest.json

Returns the semantic manifest used to compile a style.

Operation id: readStyleManifest
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes

Usage Retrieve an existing style's editable semantic properties.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	Preset id or profile slug.

Operation-specific errors NOT_FOUND

Compile a style manifest

POST /styles/compile

Compiles a semantic manifest into a validated MapLibre style, returning a bundle hash and an optional diff against a base preset.

Operation id: compileStyle
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: Yes
Agent tool: geo_style operation preview

Usage Validate and preview style changes before saving a profile.

Considerations Submit a semantic manifest or preset patch; raw MapLibre JSON is not accepted.

Parameter	Location	Type	Constraints	Description
`manifest`	body	object	—	A complete style manifest.
`base`	body	string	one of light, dark, operations, solarized-light, solarized-dark, mapsource	Preset to patch instead, which adds a diff to the response.
`patch`	body	object	—	Semantic overrides merged onto the base.
`include`	body	string	one of style, summary	summary omits the compiled style.

Operation-specific errors STYLE_INVALID

Save a basemap profile

POST /styles/profiles

Saves a semantic manifest as a named profile associated with the authenticated key.

Operation id: saveStyleProfile
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: Yes
Agent tool: geo_style operation save

Usage Store a style for subsequent retrieval, editing, and rendering.

Parameter	Location	Type	Constraints	Description
`name` *	body	string	max length 120	Human name.
`slug`	body	string	max length 48	Stable URL id. Defaults to a slug of the name.
`description`	body	string	max length 400	Profile description.
`manifest`	body	object	—	The manifest to save.
`base`	body	string	—	Preset to patch instead.
`patch`	body	object	—	Semantic overrides.

Operation-specific errors STYLE_INVALID, PROFILE_LIMIT_REACHED

Generate a style from a text description

POST /styles/intent

Converts text into a semantic manifest and compiled style. Returns matched vocabulary, applied changes, the bundle hash, and validation results.

Operation id: generateStyleFromIntent
Access: Subscription key
Quota weight: 2
Latency class: fast
Deterministic: Yes
Agent tool: geo_style operation intent

Usage Create an initial basemap style from a description, then review the proposed manifest.

Considerations Use compileStyle for an existing manifest or explicit property changes.

Parameter	Location	Type	Constraints	Description
`intent` *	body	string	min length 3, max length 2000	Text description of the desired basemap style.
`base`	body	string	one of light, dark, operations, solarized-light, solarized-dark, mapsource	Preset to build on. Defaults to one the intent implies.
`save`	body	boolean	default false	Save the result as a profile revision on this key.
`name`	body	string	max length 120	Profile name when saving.
`slug`	body	string	max length 48	Profile slug when saving.
`include`	body	string	one of style	style also returns the compiled MapLibre document.

Operation-specific errors STYLE_INVALID, PROFILE_LIMIT_REACHED

Read the semantic style JSON Schema

GET /styles/schema.json

Returns the JSON Schema for semantic manifests, including schema and compiler versions.

Operation id: readStyleSchema
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation schema

Usage Validate manifests locally or generate editor controls from the schema.

Considerations Use /api/basemap/contract for layer definitions and supported properties.

No parameters.

List a profile's immutable revisions

GET /styles/{id}/revisions

Lists saved profile revisions, newest first, with manifest hashes and revision-specific style URLs.

Operation id: listStyleRevisions
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation revisions

Usage Select a fixed revision for rendering or retrieve an earlier manifest.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	Profile id or slug.

Operation-specific errors NOT_FOUND

Compare two revisions at the semantic level

GET /styles/{id}/diff

Compares profile revisions and returns changed semantic properties with previous and updated values.

Operation id: diffStyleRevisions
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation diff

Usage Review property changes before applying a style revision.

Considerations This endpoint compares semantic manifests, not compiled MapLibre documents.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	Profile id or slug.
`from`	query	integer	—	Earlier revision. Defaults to the one before `to`.
`to`	query	integer	—	Later revision. Defaults to the current one.

Operation-specific errors NOT_FOUND

Delete a saved basemap profile

DELETE /styles/profiles/{id}

Remove a profile from this key.

Operation id: deleteStyleProfile
Access: Subscription key
Quota weight: 1
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation delete

Usage Remove an unused profile or release capacity for a new profile.

Parameter	Location	Type	Constraints	Description
`id` *	path	string	—	Profile id or slug.

Operation-specific errors NOT_FOUND

List label fontstacks

GET /glyphs

Lists hosted fontstacks and fonts uploaded with the authenticated key.

Operation id: listFontstacks
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_style operation fonts

Usage Check available font names before configuring label typography.

No parameters.

Upload a font

POST /fonts

Convert a TTF, OTF or WOFF to SDF glyph ranges and report the Unicode blocks it covers.

Operation id: uploadFont
Access: Subscription key
Quota weight: 6
Latency class: batch
Deterministic: Yes
Agent tool: geo_style operation upload_font

Usage Add a custom label font and inspect its supported Unicode ranges.

Parameter	Location	Type	Constraints	Description
`name` *	body	string	max length 64	The stack name a style will refer to.
`data` *	body	string	—	The font file, base64-encoded.
`license`	body	string	max length 200	Recorded with the font; not verified.

Operation-specific errors PROFILE_LIMIT_REACHED

Delete an uploaded font

DELETE /fonts/{name}

Remove a font from this key.

Operation id: deleteFont
Access: Subscription key
Quota weight: 1
Latency class: instant
Deterministic: Yes

Usage Remove an unused custom font and release its storage allocation.

Parameter	Location	Type	Constraints	Description
`name` *	path	string	—	The font name.

Operation-specific errors NOT_FOUND

Tiles, glyphs and rendering

Render a static map

POST /render/static

Renders a viewport and overlays as a PNG. Dark and light styles use raster tiles; other style names use vector rendering. The x-mapsource-render header includes style, dataset, result-handle, render-engine, and request metadata.

Operation id: renderStaticMap
Access: Subscription key
Quota weight: 8
Latency class: batch
Deterministic: Yes
Agent tool: geo_render operation static
Accepts handles: feature_collection, route, isochrone, analysis, place_collection

Usage Generate static maps for reports, previews, and geographic visualizations.

Considerations Use data endpoints for feature attributes or editable geometry.

Parameter	Location	Type	Constraints	Description
`lat`	body	number	min -85.05112878, max 85.05112878	Viewport centre latitude.
`lon`	body	number	min -180, max 180	Viewport centre longitude.
`zoom`	body	number	min 0, max 19	Zoom level.
`bbox`	body	array	—	[west, south, east, north]; fits the viewport to it.
`width`	body	integer	min 64, max 2048, default 800	Image width.
`height`	body	integer	min 64, max 2048, default 600	Image height.
`style`	body	string	default "dark"	dark or light composite raster; any other name is a preset or saved profile rendered as vector.
`styleRevision`	body	integer	min 1	Saved profile revision to use for rendering.
`bearing`	body	number	min -180, max 180, default 0	Vector renders only.
`pitch`	body	number	min 0, max 60, default 0	Vector renders only.
`geojson`	body	object	—	GeoJSON to draw, or a result handle.
`markers`	body	array	max 50	Up to fifty markers with optional labels.

Operation-specific errors HANDLE_EXPIRED, NOT_FOUND

Read a vector tile

GET /tiles/vector/{z}/{x}/{y}.pbf

OpenMapTiles-schema Mapbox Vector Tile.

Operation id: getVectorTile
Access: Subscription key
Quota weight: 1
Latency class: instant
Deterministic: Yes

Usage Render or inspect vector features in a map client. Configure source zoom using nativeMaxZoom.

Parameter	Location	Type	Constraints	Description
`z` *	path	integer	min 0, max 20	Zoom.
`x` *	path	integer	—	Tile column.
`y` *	path	integer	—	Tile row.

Read a raster basemap tile

GET /tiles/{style}/{z}/{x}/{y}.png

A rendered 256-pixel CARTO basemap tile.

Operation id: getRasterTile
Access: Subscription key
Quota weight: 1
Latency class: instant
Deterministic: Yes

Usage Display a pre-rendered dark or light basemap without style compilation.

Parameter	Location	Type	Constraints	Description
`style` *	path	string	one of dark, light	dark or light.
`z` *	path	integer	min 0, max 20	Zoom.
`x` *	path	integer	—	Tile column.
`y` *	path	integer	—	Tile row.

Render a custom style as a raster tile

GET /tiles/styles/{style}/{z}/{x}/{y}.png

Renders a 256-pixel XYZ PNG from any shipped vector preset or an owned saved style profile. A profile can be pinned to a revision.

Operation id: renderStyleTile
Access: Subscription key
Quota weight: 8
Latency class: batch
Deterministic: Yes

Usage Display a Mapsource vector preset or fully customized saved style in a raster-only map client.

Parameter	Location	Type	Constraints	Description
`style` *	path	string	—	Preset ID or an owned profile slug.
`z` *	path	integer	min 0, max 20	Zoom.
`x` *	path	integer	—	Tile column.
`y` *	path	integer	—	Tile row.
`revision`	query	integer	min 1	Optional saved profile revision.

Operation-specific errors NOT_FOUND, UPSTREAM_UNAVAILABLE

Read an SDF glyph range

GET /glyphs/{fontstack}/{range}.pbf

Returns SDF glyphs for a fontstack. For multi-face stacks, the first face containing the requested range is used.

Operation id: readGlyphRange
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes

Usage Supply label glyphs to a MapLibre client rendering a compiled style.

Parameter	Location	Type	Constraints	Description
`fontstack` *	path	string	—	One face, or several separated by commas.
`range` *	path	string	—	A 256-codepoint range such as 0-255.

Operation-specific errors NOT_FOUND

Service state and metrics

Read per-subsystem availability and dataset freshness

GET /status

Reports each subsystem independently, the OSM dataset timestamp, minute-diff replication state and lag in seconds, whether machine payment can settle, the deployed Overpass engine version, and for every dataset the engine build serving it and the data snapshot it answers from. overpass.displayVersion is read from the running engine binary (for example "0.7.62.11 87bfad18") and changes automatically when production is upgraded.

Operation id: readServiceStatus
Access: Public
Quota weight: free
Latency class: instant
Deterministic: No
Agent tool: geo_data operation status

Usage Monitor service availability, dataset freshness, payment settlement readiness, and the engine and dataset versions behind each answer.

Considerations Poll at an appropriate interval; status checks are not required before every API call.

No parameters.

Read request rates, latencies and data freshness

GET /metrics

Request rates, success rates, p50/p95/p99 latency, failure counters, dataset ages, and handle usage for the selected time window.

Operation id: readMetrics
Access: Subscription key
Quota weight: free
Latency class: fast
Deterministic: No
Agent tool: geo_data operation metrics

Usage Monitor performance and identify slow operations or stale datasets.

Considerations Use /api/status for current service availability.

Parameter	Location	Type	Constraints	Description
`window`	query	integer	min 1, max 1440, default 60	Minutes to measure over.

Discover basemap tile sources

GET /tiles/catalog

Tile templates, source and layer zoom ranges, tileset versions, snapshot dates, and attribution. nativeMaxZoom identifies the highest generated tile resolution.

Operation id: readBasemapCatalog
Access: Public
Quota weight: free
Latency class: instant
Deterministic: Yes
Agent tool: geo_data operation basemaps

Usage Configure tile sources and supported zoom levels before initializing a map.

No parameters.

Organizations, projects and credentials

Read account and credential details

GET /account

Returns the organization, projects, and authenticated credential's scopes, project, and identity type.

Operation id: readAccount
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Inspect account membership, project attribution, and credential permissions.

No parameters.

Create a project

POST /account/projects

Creates a project for organizing credentials, usage, and budgets by workload or environment.

Operation id: createProject
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Separate development, staging, production, or other account workloads.

Parameter	Location	Type	Constraints	Description
`name` *	body	string	max length 120	Human name.
`slug`	body	string	max length 48	Stable id. Defaults to a slug of the name.
`environment`	body	string	one of development, staging, production, default "production"	Which environment this project is.

Operation-specific errors NOT_FOUND

Archive a project

DELETE /account/projects/{project}

Archives a project while preserving its usage history.

Operation id: archiveProject
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Deactivate a project that is no longer in use.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.

Operation-specific errors NOT_FOUND

List a project's service accounts

GET /account/projects/{project}/service-accounts

Lists service-account identities associated with a project.

Operation id: listServiceAccounts
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Review service accounts configured for a project's automated workloads.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.

Operation-specific errors NOT_FOUND

Create a service account

POST /account/projects/{project}/service-accounts

Creates an identity for automated workloads with independently managed credentials.

Operation id: createServiceAccount
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Assign a dedicated identity to an application, integration, or agent.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.
`name` *	body	string	max length 120	Service account name.
`description`	body	string	max length 400	Service account description.

Operation-specific errors NOT_FOUND

Disable a service account

DELETE /account/projects/{project}/service-accounts/{id}

Disables a service account and revokes its credentials in one transaction.

Operation id: disableServiceAccount
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Revoke access for a workload or compromised service account.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.
`id` *	path	string	—	Service account id.

Operation-specific errors NOT_FOUND

List a project's credentials

GET /account/projects/{project}/keys

Lists scopes, labels, identities, expiry, and revocation status. Secret key values are excluded.

Operation id: listProjectKeys
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Review credentials and access permissions for a project.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.

Operation-specific errors NOT_FOUND

Issue a scoped credential

POST /account/projects/{project}/keys

Issues a scoped API key with an optional service-account association and expiry. The secret is returned once.

Operation id: issueProjectKey
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Create a credential with permissions for a specific workload.

Considerations Service-account credentials cannot issue additional credentials.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.
`label`	body	string	max length 120	Credential label.
`scopes`	body	array	—	Capability categories this key may use, or * for all. Defaults to *.
`serviceAccountId`	body	string	—	Bind the key to an agent identity.
`expiresInDays`	body	integer	min 1, max 3650	Expire the key automatically.

Operation-specific errors NOT_FOUND

Revoke a credential

DELETE /account/projects/{project}/keys/{id}

Immediately revokes a credential while retaining usage records.

Operation id: revokeProjectKey
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Revoke a compromised credential or remove access for a retired workload.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.
`id` *	path	string	—	Key id, not the secret.

Operation-specific errors NOT_FOUND

Set a project usage budget

PUT /account/projects/{project}/budget

Configures request budgets. A soft limit adds a warning header; a hard limit rejects requests with BUDGET_EXCEEDED.

Operation id: setProjectBudget
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Set project usage thresholds before automated or high-volume work.

Parameter	Location	Type	Constraints	Description
`project` *	path	string	—	Project id or slug.
`period`	body	string	one of month, day, default "month"	Window the budget counts over.
`softRequests`	body	integer	min 0	Warn past this many accepted requests. null removes it.
`hardRequests`	body	integer	min 0	Refuse past this many. null removes it.

Operation-specific errors NOT_FOUND

Read usage attributed by project

GET /account/usage

Returns accepted requests, response bytes, and budgets for each project in the current period.

Operation id: readAccountUsage
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Monitor project-level consumption and allocate usage across workloads.

No parameters.

Read the audit trail

GET /account/audit

Lists organization changes to credentials, projects, service accounts, and budgets in reverse chronological order, with actor information.

Operation id: readAccountAudit
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No

Usage Review account changes and the identity responsible for each action.

No parameters.

Read usage for this key

GET /usage

Returns accepted-request totals, plan limits, and the quota reset time for the authenticated key.

Operation id: readUsage
Access: Subscription key
Quota weight: free
Latency class: instant
Deterministic: No
Agent tool: geo_data operation usage

Usage Monitor consumption and remaining allowance before additional requests.

No parameters.

Questions about this guide? Contact support.