Client setup

JavaScript and TypeScript

Install the typed client in your server application. It derives request and response types from Mapsource’s published OpenAPI contract and reads MAPSOURCE_API_KEY automatically in Node.js.

npm i mapsource

import { createClient } from "mapsource";

const mapsource = createClient();
const { data, error, response } = await mapsource.POST("/interpreter", {
  body: '[out:json][timeout:30];nwr["building"](47.60,-122.34,47.61,-122.33);out geom 100;',
});
if (error) throw new Error("Mapsource request failed: HTTP " + response.status);
console.log("Returned objects:", data.elements.length);

Supply the key through the process environment or the client’s apiKey option, never a public frontend variable. Raw fetch remains supported when a dependency-free integration is preferable.

Python

With the requests package installed, use a form-encoded body or raw QL. This example applies separate connection and response timeouts.

import os
import requests

query = """
[out:json][timeout:30];
nwr["amenity"="cafe"](47.60,-122.34,47.62,-122.31);
out geom 100;
"""
response = requests.post(
    "https://api.mapsource.io/interpreter",
    headers={"Authorization": "Bearer " + os.environ["MAPSOURCE_API_KEY"]},
    data={"data": query},
    timeout=(10, 40),
)
response.raise_for_status()
data = response.json()
print("Returned objects:", len(data["elements"]))

Do not install the Mapsource Authorization header globally on a client that also calls a third-party geocoder or downloads other resources.

Browser maps

The MapLibre example scopes authentication to Mapsource tile URLs. Preserve map center and zoom when changing the raster source. Overpass geometry must be converted into a GeoJSON layer; PNG basemaps do not contain selectable features, though the vector template does expose styleable and queryable layers.

For a public application, keep the subscription key on your server. Authenticate your own users, limit allowed routes and query sizes, and proxy requests to Mapsource. Do not make that proxy an unrestricted public relay. The examples repository includes a local server-side map demo.

Attribution and place labels

Load the Map UI stylesheet after MapLibre’s stylesheet, and install the helper immediately after creating the map. Attribution starts collapsed and remains available through its keyboard-accessible toggle. Its text, links, background, and font follow the selected basemap.

<link rel="stylesheet" href="https://mapsource.io/map-ui/v1/map-ui.css">

import {
  installMapsourceUI, deriveMapTheme,
  formatPlaceFeature, createPlaceLayers
} from "https://mapsource.io/map-ui/v1/map-ui.mjs";

// Create your map with attributionControl: { compact: true }.
const disposeUI = installMapsourceUI(map);
let places = [];
let selectedId = null;

function renderPlaces() {
  map.off("idle", renderPlaces);
  if (!map.isStyleLoaded()) {
    map.once("idle", renderPlaces);
    return;
  }
  const sourceId = "search-results";
  const data = {
    type: "FeatureCollection",
    features: places.map(place => formatPlaceFeature(place, {
      selected: place.id === selectedId
    }))
  };
  const source = map.getSource(sourceId);
  if (source) source.setData(data);
  else map.addSource(sourceId, { type: "geojson", data });
  for (const layer of createPlaceLayers(deriveMapTheme(map.getStyle()), {
    source: sourceId, idPrefix: "search-results"
  })) {
    if (map.getLayer(layer.id)) map.removeLayer(layer.id);
    map.addLayer(layer);
  }
}

// Call with results from /places/lookup or /places/discover.
function showPlaces(results, selected = null) {
  places = results;
  selectedId = selected;
  renderPlaces();
}
map.on("style.load", renderPlaces);

// On component teardown, before map.remove():
// map.off("style.load", renderPlaces);
// map.off("idle", renderPlaces);
// disposeUI();

Result labels show the supplied title, category, and address above their point. Labels use the basemap’s POI font and color with a contrasting halo. Collision detection limits overlap; the selected result stays labeled. Keep a selectable result list for crowded maps and keyboard access. No missing business details are inferred.

Compiled styles include metadata["mapsource:ui"] with the resolved control and POI theme. Style JSON alone cannot style HTML attribution or install result layers: applications must load the helper, or implement equivalent behavior. The helper updates control colors on style changes; restore your result source and layers on style.load, as above.

The stylesheet includes browser Noto Sans fonts matching the shipped font families. Custom fonts need both a Mapsource glyph stack for map labels and an application-hosted @font-face for HTML controls. A glyph PBF is not a browser font. Raster styles also need a glyphs URL when displaying result labels; use https://api.mapsource.io/glyphs/{fontstack}/{range}.pbf.

These public helper assets require no API key. Load them directly with module imports or vendor them with the included font license. If you restrict Content Security Policy, permit the helper origin for scripts, styles, and fonts. Continue routing authenticated data requests through your application’s protected backend; never send credentials to the helper asset URLs.

Existing Overpass clients

Clients differ in what they append to an Overpass base URL. The full endpoint is https://api.mapsource.io/interpreter; a client that appends /interpreter uses https://api.mapsource.io as its base. Confirm the final request URL, not just the configured base.

Every path also works with an /api prefix (https://api.mapsource.io/api/interpreter), which is the form https://mapsource.io serves.

Never combine these forms, even with the same value. Website URLs reject key parameters. Avoid copying keyed URLs into screenshots, tickets, notebooks, or shared configurations.

OSMnx, JOSM, and Overpass Turbo

Use a header-capable connection or an authenticated proxy when a tool only exposes a server URL. OSMnx may contact a separate geocoder; do not use a global Authorization setting that forwards your Mapsource key there. Also check the tool’s generated timeout and disable any assumption that the public Overpass queue-status endpoint is available here.

For GUI clients such as JOSM and Overpass Turbo, verify header support in the installed version before replacing a production connection. Mapsource’s /status is JSON service status, not the public Overpass text queue protocol. The Python and JavaScript examples above give you explicit control of both the request and credential.

Engine version

The currently deployed Overpass engine version is published by GET /status; see overpass.displayVersion. It identifies the engine build currently serving Mapsource requests and changes automatically when production is upgraded. Response generator values and the X-Mapsource-Overpass-Version header report the same engine.

Connection checklist

1. Store the API key securely and scope the header to Mapsource.
2. Verify the complete interpreter URL and supported request content type.
3. Use an explicit timeout within your plan limits.
4. Check engine mode and timestamp before interpreting results.
5. Handle unsuccessful HTTP responses, interrupted streams, and quota resets.
6. Display source attribution when publishing a map or derived data.