API quickstart

Your endpoint

https://api.mapsource.io/interpreter

Every path also works with an /api prefix, the form https://mapsource.io serves.

Get a key from pricing. Explorer requires verified email and reveals its key once after verification. Paid checkout reveals a key after payment; a verified account is optional but recommended for recovery. Save every revealed key securely—your application uses it directly and no website password replaces it.

Send your key in a header

Authorization: Bearer $MAPSOURCE_API_KEY

Set MAPSOURCE_API_KEY through your deployment’s secret manager or an uncommitted environment file. Do not print it or put it in URLs. URL credentials can be recorded by browsers, proxies, and analytics.

The interpreter also accepts legacy path and query credentials for compatible clients; the client guide documents the exact routes and their limitations. Send a credential in only one location.

Run a first query

This query selects cafés in a small Seattle bounding box. nwr includes nodes, ways, and relations. out geom 100 requests geometry for at most 100 objects; it does not guarantee that every matching feature is returned.

curl --fail-with-body --max-time 40 "https://api.mapsource.io/interpreter" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  -H "Content-Type: text/plain" \
  --data '[out:json][timeout:30];nwr["amenity"="cafe"](47.60,-122.34,47.62,-122.31);out geom 100;'

Bounding boxes are ordered south, west, north, east. Use a smaller area or more specific tags for expensive queries. See client setup for JavaScript and Python examples.

Read the response

JSON results contain elements. Nodes have latitude and longitude; ways and relations can include geometry when requested. Tags describe features such as roads, buildings, addresses, parks, water, shops, or amenities. Request out meta when you need element version and edit metadata.

osm3s.timestamp_osm_base identifies the source dataset timestamp. The X-Overpass-Engine-Mode header identifies the query engine. See service status for endpoint availability and replication progress.

X-Request-Id: …
X-RateLimit-Limit: 60
X-Quota-Limit: 50000
X-Quota-Remaining: 49999
X-Quota-Reset: <Unix timestamp in seconds>

Header values above illustrate a Core response. Check HTTP status before parsing results, and follow error codes and Retry-After when a request fails.

Display a raster or vector basemap

Dark and light are 256 px raster PNGs served to zoom 20. The vector template returns an OpenMapTiles-schema Mapbox Vector Tile to zoom 14, which you style on the client and can query for individual features. The free catalog lists every template with its zoom range, snapshot date, and attribution. Each fetched tile uses your monthly request allowance.

curl "https://api.mapsource.io/tiles/catalog"

curl --fail-with-body "https://api.mapsource.io/tiles/dark/12/656/1429.png" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output tile.png

curl --fail-with-body "https://api.mapsource.io/tiles/vector/12/656/1429.pbf" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output tile.pbf

For a private browser tool where the user provides their own key, MapLibre can attach the header only to Mapsource tile requests. Do not embed your service key in a public application; use an authenticated server-side proxy instead.

Load https://mapsource.io/map-ui/v1/map-ui.css after MapLibre’s CSS for themed, initially collapsed attribution. See attribution and place labels for the shared integration helper.

import { installMapsourceUI } from "https://mapsource.io/map-ui/v1/map-ui.mjs";
const origin = "https://api.mapsource.io";
const style = "dark"; // Change to "light" for Positron, or use the vector source below.
const map = new maplibregl.Map({
  container: "map",
  attributionControl: { compact: true },
  center: [-122.33, 47.61], zoom: 12,
  style: {
    version: 8,
    metadata: { "mapsource:ui": {
      version: 1,
      background: style === "light" ? "#f7f7f5" : "#0e1013",
      foreground: style === "light" ? "#3d3d3d" : "#d6d6d6",
      fontStack: ["Noto Sans Regular"]
    } },
    glyphs: origin + "/glyphs/{fontstack}/{range}.pbf",
    sources: {
      mapsource: {
        type: "raster", tileSize: 256,
        tiles: [origin + "/tiles/" + style + "/{z}/{x}/{y}.png"],
        attribution: "© OpenMapTiles · © OpenStreetMap contributors · CARTO"
      }
    },
    // For vector instead, declare:
    //   mapsourceVector: { type: "vector", maxzoom: 14,
    //     tiles: [origin + "/tiles/vector/{z}/{x}/{y}.pbf"] }
    // then add layers referencing its OpenMapTiles source-layers.
    layers: [{ id: "basemap", type: "raster", source: "mapsource" }]
  },
  transformRequest: (url) => {
    const target = new URL(url);
    return target.origin === origin && target.pathname.startsWith("/tiles/")
      ? { url, headers: { Authorization: "Bearer " + MAPSOURCE_API_KEY } }
      : { url };
  }
});
const disposeUI = installMapsourceUI(map);
// On teardown: disposeUI(); map.remove();

Raster basemaps contain rendered pixels. Vector basemaps contain client-queryable features. To display Overpass results on either, convert the response to GeoJSON and add an overlay. See the tile guide for styles, coordinates, caching, and overlays.

Elevation tiles and 3D terrain

Elevation tiles use Terrarium encoding and support zoom levels up to 15. Configure a MapLibre raster-dem source with encoding: "terrarium" for hillshading and 3D terrain.

curl --fail-with-body "https://api.mapsource.io/terrain/12/663/1467.png" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" --output dem.png

map.addSource("terrain", {
  type: "raster-dem",
  tiles: ["https://api.mapsource.io/terrain/{z}/{x}/{y}.png"],
  encoding: "terrarium",   // Mapzen encoding, not Mapbox
  tileSize: 256, maxzoom: 15
});
map.setTerrain({ source: "terrain", exaggeration: 1.4 });
map.easeTo({ pitch: 60 });

Coordinates without source data return HTTP 204 with an empty body.

Routing

Turn-by-turn routing over the global OpenStreetMap road graph for auto, bicycle, pedestrian, truck, motor_scooter, and bus. The response returns distance, duration, a GeoJSON LineString, and maneuver text. Two waypoints minimum, ten maximum.

curl --fail-with-body "https://api.mapsource.io/route" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locations":[{"lat":47.6062,"lon":-122.3321},
                    {"lat":47.6205,"lon":-122.3493}],
       "costing":"bicycle","elevation":true}'

Set elevation: true to include a terrain profile with gainMeters and lossMeters. Elevation values are sampled from the terrain dataset along the route.

An unroutable request returns HTTP 422. Adjust the waypoints or travel mode before retrying. Routes are not certified for safety-critical navigation.

Isochrones

Reachable-area polygons from one origin, up to four travel-time bands of 1 to 60 minutes. Useful for catchment, coverage, and site selection. Pair a returned polygon with an Overpass poly: query to answer “what is reachable within N minutes” in two calls.

curl --fail-with-body "https://api.mapsource.io/isochrone" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat":47.6062,"lon":-122.3321,
       "costing":"pedestrian","contours":[5,10,15]}'

Topographic contours

Vector contour bands for any land coordinate at a chosen resolution and band count. Each path carries its elevation in metres, an index flag for heavier drawing, and labelPath, an along-band path for placing elevation labels. Fewer bands than requested come back where relief is low.

curl --fail-with-body \
  "https://api.mapsource.io/contours?lat=45.3736&lon=-121.6959&zoom=10&bands=14" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

Zoom accepts 6 to 13 and bands 4 to 24. The paths are drawn in a fixed viewBox; use the returned bounds to map them onto geographic coordinates.

Request point elevation

curl --fail-with-body "https://api.mapsource.io/elevation?lat=45.3735&lon=-121.6959" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

The JSON response includes elevationMeters, belowSeaLevel, sampledMeters, coordinates, source, sampling zoom, bathymetryTile, and attribution. This is sampled terrain height, not building height. elevationMeters is a surface height floored at sea level, so a point at sea reads 0 and belowSeaLevel marks it; the raw model reading stays in sampledMeters. For the sea floor itself, read bathymetryTile, the public AWS Open Data raster each sample came from. Read the elevation guide for coordinate limits and source resolution.

Address and business search

Find an address, business, brand, landmark or place using local OSM search. Pass the map center as lat and lon to prefer nearby matches. A location qualifier such as Starbucks in Portland takes priority over that bias.

curl --fail-with-body \
  "https://api.mapsource.io/places/lookup?q=Starbucks&lat=45.52&lon=-122.68&limit=8" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

The mapsource-lookup.v1 response includes string OSM IDs, coordinates, supplied address fields, ranking scores and ambiguity. When bestMatchId is null, let the user select a result. Requested house numbers are not substituted. Check coverage and warnings: regional fallback results are not a global address search.

Use regional discovery to list businesses inside a viewport, polygon or travel-time area. This request finds cafés within a 15-minute walk and ranks the nearest 25 candidates by measured travel time:

curl --fail-with-body "https://api.mapsource.io/places/discover" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"lat":45.52,"lon":-122.68,"minutes":15,"costing":"pedestrian","category":"coffee","rankBy":"travel_time","limit":8}'

Read the address and business search guide for filters, pagination, source coverage and regional limits. MCP clients use geo_search with operation: lookup or operation: discover. Both are included in every subscription plan; see shared request accounting for composed calls.

The interactive map below accepts phrases such as “find coffee near me”, “show pharmacies in this area”, and “cafés within a 15-minute walk”. Each search shows its interpretation, a selectable list and map markers. “Near me” means the current map viewport; use the browser location button to center on your position. Travel-time searches use the map center, or a location you select for an explicit qualifier, and support 1–30 whole minutes by foot, car or bike. These are fixed phrase rules; hours, ratings, prices and additional conditions are not supported. Use the custom-basemap studio for the full vector styling workflow.

Existing /geocode clients remain supported. New local search integrations should use /places/lookup.

Pay per query without a subscription

x402 supports individual query payments in USDC on Base mainnet. An unpaid request returns HTTP 402 with a PAYMENT-REQUIRED header specifying the network, asset, recipient, and price. Obtain authorization for the amount before signing a payment.

# The first call returns 402 with the payment requirement.
curl -i --fail-with-body "https://api.mapsource.io/x402/interpreter" \
  -H "Content-Type: application/json" \
  -d '{"query":"[out:json][timeout:25];node(1);out;"}'

The payments entry in service status reports settlement availability. See x402 integration for signing and settlement handling.

Usage and status

Read your own consumption without exposing query content, and check per-endpoint availability. The status document reports each endpoint separately, so a single unavailable service does not imply the rest are down.

curl --fail-with-body "https://api.mapsource.io/usage" \
  -H "Authorization: Bearer $MAPSOURCE_API_KEY"

curl "https://api.mapsource.io/status"          # public, no key required
curl "https://api.mapsource.io/tiles/catalog"   # public tile templates

Connect an agent

Give your agent the service contract and endpoints, then supply your key through its secret configuration. The agent guide covers remote MCP tools and x402 query payments.

Limits, billing, and attribution

• Plans and limits: request volume, concurrency, timeouts, memory, and response size.
• Usage, billing, and keys: usage history, invoices, cancellation, and key replacement.
• Compatibility: request formats, defaults, generated areas, and unsupported historical queries.
• Attribution: OpenStreetMap, CARTO, OpenMapTiles, and elevation sources.