MapJet API

MapJet is a shared app of the Substrio stack: geo services (IP location, address search and geocoding, city centres, time zones) and vector map tiles for any Substrio account. You call it with an account key of your own account, scoped to the mapjet app. Every call counts against your account's MapJet plan.

Get a key

MapJet's owner keeps the app open to other accounts' keys (account.app.open.set, PUT /v1/_accounts/{id}/apps/mapjet/keys-open with {"open": true}). With that, any account makes its own key for it:

curl -X POST https://<platform host>/v1/_accounts/<your account id>/keys \
  -H "Authorization: Bearer <your account key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "mapjet-prod", "apps": ["mapjet"], "mode": "live"}'

The answer holds the key's secret once. The key works only at MapJet, as a customer of the app: it reads nothing else of your account. Give it its own limits if you want them (requests_per_minute, request_budget; see account.key.update). MCP: substrio_account_key_create with the same fields.

Call it

Send the key as a bearer token, at MapJet's host or with X-Substrio-Tenant: mapjet:

curl https://<platform host>/lookup/8.8.8.8 \
  -H "X-Substrio-Tenant: mapjet" \
  -H "Authorization: Bearer <key>"

A request MapJet refuses (400) is not charged. Tiles count on their own counter, tiles; every other route counts on requests.

Maps

Give MapLibre GL JS a theme's style and send the key with every request to MapJet:

const MAPJET = 'https://<platform host>';
const headers = { 'X-Substrio-Tenant': 'mapjet', Authorization: 'Bearer <key>' };
const map = new maplibregl.Map({
  container: 'map',
  style: `${MAPJET}/styles/dark`,
  transformRequest: (url) => (url.startsWith(MAPJET) ? { url, headers } : { url }),
});

The themes: light (Daylight), dark (Midnight), streets, hybrid, terrain and mono (Ink). Every map shows the credit the style carries (MapJet, and "© OpenStreetMap contributors", which the data's licence requires).

Saved maps

Make a map of your own in the admin's Studio (or by POST /maps), then load it by its id. A change to the map is what every site that loads the id draws at its next load, with no deploy of yours.

{ "name": "Fleet", "base": "light", "night": "dark",
  "overrides": { "accent": "#00aa66", "highway": "#ff5500" },
  "options": { "density": "rich", "language": "en", "buildings": "3d", "pois": true, "rail": true, "boundaries": true } }

• base, night: a theme; the night style carries your brand colours (accent, highway, major, park, boundary) over the night theme's own land, water and text.
• overrides: accent, land, water, park, highway, major, building, text, boundary, each #rrggbb. Labels are held readable (4.5 : 1 on the land) whatever you pick.
• options.density: none, minimal, normal, rich; language: local or en, es, fr, de, it, pt, nl, pl, ru, tr, ar, hi, ja, ko, zh; buildings: 3d, flat, none.
• layers: your own data over the map, drawn in the order given, each { "name", "color": "#rrggbb", "clusters": true, "heatmap": true, "data": <GeoJSON> }. data is a FeatureCollection (points, lines, polygons). The save answers each layer's id; send { "id", "name", "color", ... } without data to keep a layer as it is and change only how it is drawn, or new data for a new layer. clusters groups nearby points into counted circles as the map zooms out, and heatmap draws their density; both take points, and both run in the viewer's browser. The style loads each layer from GET /maps/:id/layers/:layer, once: a layer's URL never changes its data, so the browser keeps it.

Follow the viewer's day or night setting:

const dark = matchMedia('(prefers-color-scheme: dark)');
const styleUrl = () => `${MAPJET}/maps/<id>/${dark.matches ? 'night' : 'style'}`;
const map = new maplibregl.Map({ container: 'map', style: styleUrl(), transformRequest });
dark.addEventListener('change', () => map.setStyle(styleUrl(), { diff: true }));

Markers

MapJet's markers draw a place in the map's theme accent: pin for an exact place (it drops in and pulses at its foot), approximate for an area a place may be in, such as an IP's city (a sonar ping at the true radius in metres, at every zoom). The animations run on the compositor, and stop for a visitor who asks for reduced motion.

const { pin, approximate } = await import(`${MAPJET}/lib/[email protected]/mapjet-markers.js`);
map.on('load', () => {
  pin(map, [-115.1398, 36.1699]);
  approximate(map, [-115.14, 36.17], 5000).setRadius(2500);
});

The same module has spotlight(map, [lng, lat], metres, { dim }), which dims the world around a place, and tour(map, stops, { loop, onEnd }), a camera flight through { center, zoom, bearing, pitch, duration, hold } stops (each stop without the flight for a viewer who asks for reduced motion).

Plans

Past your plan, a call answers 429, nothing is counted, and the body says when it frees:

{"error": "Too Many Requests", "code": "USAGE_LIMIT", "counter": "requests",
 "limit": 1000, "used": 1000, "period": "day", "resets_at": 1798761600}

Other answers

Data

IP places: DB-IP's IP to City Lite (CC BY 4.0, "IP Geolocation by DB-IP"). US addresses: Netsyms' AddressDatabase. Time zones: tz-lookup's tables (built from timezone-boundary-builder). Map tiles: MapJet's own, served from MapJet, built from OpenStreetMap (ODbL, "© OpenStreetMap contributors").