Download OpenAPI specification:
Routing, geocoding and map tiles for Zambia and beyond.
Beehive Maps is a metered gateway over open geospatial data. Every request is authenticated by API key, authorized against that key's scopes, rate limited, and metered in billable units.
Send your key as a bearer token:
Authorization: Bearer bmk_live_a1b2c3d4e5f6g7h8i9j0k1_<secret>
Browser contexts that cannot set headers (tile requests, style loads) may
pass ?key= instead. Only browser keys should ever appear in a URL —
they are restricted by HTTP referrer and carry narrower scopes precisely
because they are visible to anyone using your site.
| Type | Prefix | Restriction | Use |
|---|---|---|---|
| Server | bmk_live_ / bmk_test_ |
IP allowlist | backends, never shipped to clients |
| Browser | bmp_live_ / bmp_test_ |
HTTP referrer allowlist | web and mobile clients |
Keys in the test environment are free and unmetered, and return real
responses from the same upstreams. Develop against test keys.
Two independent limits apply to every request:
A request is served only if both admit it, so effective throughput
against a single service is min(key_limit, service_limit). Both are token
buckets checked and committed atomically, so a request rejected by one never
consumes budget from the other.
Every response carries the state of the binding limit — the one closest to rejecting:
RateLimit-Limit: 10
RateLimit-Remaining: 7
RateLimit-Reset: 1
X-RateLimit-Scope: service:directions
A 429 names which limit tripped in error.details.limit, so you never have
to guess whether to slow down globally or only for one endpoint.
Requests are not equal, so they are not billed equally. A matrix of 100×100 is 10,000 elements of work and is billed as such.
| Service | Unit formula |
|---|---|
| Directions | 1 + max(0, waypoints - 2) |
| Matrix | sources × destinations |
| Snap to road | ceil(points / 10) |
| Map matching | ceil(points / 10) |
| Optimize | waypoints² |
| Geocode / reverse / autocomplete | 1 |
| Static map | 2 |
| Map session | 1 — all tiles inside the session are free |
Interactive maps are billed per session, not per tile: one map load can
fetch hundreds of tiles, and a bill nobody can predict is a bill nobody
renews. Call POST /v1/tiles/sessions, then fetch tiles with the returned
token.
Every error shares one envelope with a stable, machine-readable code.
Match on code, never on message.
Map data is © OpenStreetMap contributors, licensed ODbL. Attribution must remain visible wherever this data is displayed — it is a licence condition, and it passes through to your own end users.
Returns one or more routes with turn-by-turn steps.
Scope: directions:read · Units: 1 + max(0, waypoints - 2)
| coordinates required | string Example: coordinates=28.2833,-15.4167;28.3228,-15.3875 Semicolon-separated |
| profile | string Default: "car" Value: "car" Travel mode. Only |
| alternatives | boolean Default: false Return alternative routes where they exist. |
| steps | boolean Default: true Include turn-by-turn maneuvers. |
| geometries | string Default: "polyline6" Enum: "polyline" "polyline6" "geojson" Geometry encoding. |
| overview | string Default: "simplified" Enum: "full" "simplified" "false" |
| annotations | string Comma-separated extras, e.g. |
{- "routes": [
- {
- "distance": 0,
- "duration": 0,
- "geometry": "string",
- "legs": [
- {
- "distance": 0,
- "duration": 0,
- "summary": "string",
- "steps": [
- { }
]
}
], - "weight": 0,
- "weight_name": "string"
}
], - "waypoints": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}All-pairs durations and distances between sources and destinations.
The most expensive endpoint per request: cost grows with
sources × destinations, so a 50×50 matrix costs 2,500 units. Request
only the pairs you need — sources and destinations restrict the
matrix rather than forcing a full square.
Scope: matrix:read · Units: sources × destinations
| coordinates required | string Example: coordinates=28.2833,-15.4167;28.3228,-15.3875 Semicolon-separated |
| sources | string Example: sources=0;1 Indices into |
| destinations | string Example: destinations=2;3 Indices into |
| annotations | string Default: "duration,distance" Enum: "duration" "distance" "duration,distance" |
{- "durations": [
- [
- 0
]
], - "distances": [
- [
- 0
]
], - "sources": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0
}
], - "destinations": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Returns the nearest routable position on the road network for each coordinate. Cheap and high-volume — intended for cleaning up GPS pings before display.
Scope: snap:read · Units: ceil(points / 10)
| coordinates required | string Example: coordinates=28.2833,-15.4167;28.3228,-15.3875 Semicolon-separated |
| radius | number <= 5000 Default: 100 Maximum search radius in metres. |
{- "waypoints": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Fits a noisy GPS trace onto the road network, returning the path actually travelled. The core primitive for fleet telematics: trip reconstruction, distance-travelled billing, route adherence.
Supply timestamps whenever you have them — matching quality improves
substantially.
Scope: match:read · Units: ceil(points / 10)
| coordinates required | string Example: coordinates=28.2833,-15.4167;28.3228,-15.3875 Semicolon-separated |
| timestamps | string Semicolon-separated UNIX seconds, one per coordinate. |
| radiuses | string Per-point GPS accuracy in metres, semicolon-separated. |
| geometries | string Default: "polyline6" Enum: "polyline" "polyline6" "geojson" |
{- "matchings": [
- {
- "distance": 0,
- "duration": 0,
- "geometry": "string",
- "legs": [
- {
- "distance": 0,
- "duration": 0,
- "summary": "string",
- "steps": [
- { }
]
}
], - "weight": 0,
- "weight_name": "string",
- "confidence": 0
}
], - "tracepoints": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Solves the travelling-salesman ordering for up to 100 waypoints.
For capacities, time windows and multiple vehicles you want full vehicle routing rather than this endpoint — see the roadmap.
Scope: optimize:read · Units: waypoints²
| coordinates required | string Example: coordinates=28.2833,-15.4167;28.3228,-15.3875 Semicolon-separated |
| roundtrip | boolean Default: true Return to the first waypoint. |
| source | string Default: "first" Enum: "any" "first" |
| destination | string Default: "any" Enum: "any" "last" |
{- "trips": [
- {
- "distance": 0,
- "duration": 0,
- "geometry": "string",
- "legs": [
- {
- "distance": 0,
- "duration": 0,
- "summary": "string",
- "steps": [
- { }
]
}
], - "weight": 0,
- "weight_name": "string"
}
], - "waypoints": [
- {
- "name": "string",
- "location": [
- 0,
- 0
], - "distance": 0,
- "waypoint_index": 0,
- "trips_index": 0
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Forward geocoding. Returns GeoJSON features ordered by relevance.
Bias results toward a location with lat/lon — for a user typing into
a search box, this matters more for perceived quality than any other
parameter.
Scope: geocode:forward · Units: 1
| q required | string [ 1 .. 200 ] characters Example: q=Cairo Road, Lusaka Free-form place name or address. |
| limit | integer [ 1 .. 50 ] Default: 10 |
| lat | number [ -90 .. 90 ] Latitude to bias results toward. |
| lon | number [ -180 .. 180 ] Longitude to bias results toward. |
| bbox | string Restrict to |
| lang | string Default: "en" |
| layer | string Example: layer=city,street,house Restrict to feature types, comma-separated. |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "geometry": {
- "type": "Point",
- "coordinates": [
- 0,
- 0
]
}, - "properties": {
- "name": "string",
- "street": "string",
- "housenumber": "string",
- "postcode": "string",
- "district": "string",
- "city": "string",
- "state": "string",
- "country": "string",
- "countrycode": "string",
- "type": "string",
- "extent": [
- 0
]
}
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Reverse geocoding.
Scope: geocode:reverse · Units: 1
| lat required | number [ -90 .. 90 ] |
| lon required | number [ -180 .. 180 ] |
| limit | integer [ 1 .. 50 ] Default: 1 |
| radius | number <= 50 Default: 1 Search radius in kilometres. |
| lang | string Default: "en" |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "geometry": {
- "type": "Point",
- "coordinates": [
- 0,
- 0
]
}, - "properties": {
- "name": "string",
- "street": "string",
- "housenumber": "string",
- "postcode": "string",
- "district": "string",
- "city": "string",
- "state": "string",
- "country": "string",
- "countrycode": "string",
- "type": "string",
- "extent": [
- 0
]
}
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Prefix search tuned for search-as-you-type: typo tolerant and optimized for partial input.
Debounce to roughly 150ms in your client. Firing one request per keystroke is the single most common way to exhaust a rate limit.
Scope: geocode:autocomplete · Units: 1
| q required | string [ 1 .. 200 ] characters |
| limit | integer [ 1 .. 20 ] Default: 5 |
| lat | number |
| lon | number |
| lang | string Default: "en" |
{- "type": "FeatureCollection",
- "features": [
- {
- "type": "Feature",
- "geometry": {
- "type": "Point",
- "coordinates": [
- 0,
- 0
]
}, - "properties": {
- "name": "string",
- "street": "string",
- "housenumber": "string",
- "postcode": "string",
- "district": "string",
- "city": "string",
- "state": "string",
- "country": "string",
- "countrycode": "string",
- "type": "string",
- "extent": [
- 0
]
}
}
], - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Exchanges an API key for a short-lived tile token.
This is how interactive maps are billed: one unit per session, with every tile, glyph and style fetch inside it free. It also keeps your key out of tile URLs, and keeps tile URLs identical across customers so they stay cacheable by browsers and CDNs.
Renew when expires_at approaches; the SDK does this for you.
Scope: at least one tiles:read:* · Units: 1
| style | string Default: "road" Enum: "road" "dark" Style this session will render. Must be within the key's scopes. |
{- "style": "road"
}{- "token": "string",
- "expires_at": "2019-08-24T14:15:22Z",
- "style": "string",
- "release": "string",
- "style_url": "string",
- "tile_url_template": "string",
- "glyphs_url_template": "string",
- "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Mapbox Vector Tile in the OpenMapTiles schema.
Authenticate with a session token (?token=), not an API key. Tiles
inside a live session are free.
release pins the map data version, which is what makes these URLs
immutable and therefore cacheable forever — the same z/x/y at a given
release always returns identical bytes.
Scope: tiles:read:{style} · Units: 0 within a session
| style required | string Enum: "road" "dark" |
| release required | string Example: v1 Map data release, from the session response. |
| z required | integer [ 0 .. 16 ] |
| x required | integer |
| y required | integer |
| token required | string Tile session token. |
{- "error": {
- "code": "key_revoked",
- "message": "This API key was revoked on 2026-09-01.",
- "request_id": "req_01HQ8Z3K"
}
}Style document with tile, glyph and sprite URLs already pointed at your
session. Pass to new maplibregl.Map({ style: ... }).
Scope: tiles:read:{style} · Units: 0 within a session
| style required | string Enum: "road" "dark" |
| token required | string |
{ }Signed-distance-field glyphs for label rendering. Requested by MapLibre automatically; you rarely call this yourself. Without it, a map renders correctly but with no labels at all.
Units: 0 within a session
| fontstack required | string Example: Noto Sans Regular |
| range required | string Example: 0-255 |
| token required | string |
{- "error": {
- "code": "key_revoked",
- "message": "This API key was revoked on 2026-09-01.",
- "request_id": "req_01HQ8Z3K"
}
}Server-rendered map image for emails, PDFs, link previews and anywhere a live map is impractical.
Authenticates with an API key directly — there is no session, because there is no client to hold one.
Scope: static:read · Units: 2
| style required | string Enum: "road" "dark" |
| lon required | number |
| lat required | number |
| zoom required | number [ 0 .. 16 ] |
| width required | integer [ 32 .. 2048 ] |
| height required | integer [ 32 .. 2048 ] |
| format required | string Enum: "png" "jpg" "webp" |
| marker | Array of strings Repeatable. |
| path | string Encoded polyline to draw, e.g. a route geometry. |
| retina | boolean Default: false Render at 2× pixel density. |
{- "error": {
- "code": "invalid_coordinates",
- "message": "Coordinate 1 is outside the valid range. Expected lon,lat — did you pass lat,lon?",
- "request_id": "req_01HQ8Z3K"
}
}Billable units consumed, broken down by service and time bucket, for the key making the request or for the whole organization.
Reconcile against your invoice, drive internal dashboards, or alert before you hit a quota rather than after.
Scope: usage:read · Units: 1
| from | string <date-time> Inclusive ISO-8601 start. Defaults to the start of the current month. |
| to | string <date-time> Exclusive ISO-8601 end. Defaults to now. |
| granularity | string Default: "day" Enum: "hour" "day" "month" |
| scope | string Default: "key" Enum: "key" "organization"
|
{- "from": "2019-08-24T14:15:22Z",
- "to": "2019-08-24T14:15:22Z",
- "granularity": "string",
- "total_units": 0,
- "by_service": {
- "property1": 0,
- "property2": 0
}, - "series": [
- {
- "bucket": "2019-08-24T14:15:22Z",
- "service": "string",
- "requests": 0,
- "units": 0,
- "errors": 0
}
], - "quota": {
- "units": 0,
- "used": 0,
- "resets_at": "2019-08-24T14:15:22Z"
}, - "meta": {
- "request_id": "string",
- "billable_units": 0,
- "map_release": "string",
- "attribution": "string"
}
}Reports the gateway's dependencies individually. Returns 503 when any
hard dependency is down, so a load balancer drains this instance rather
than serving errors.
{- "status": "ok",
- "map_release": "string",
- "checks": {
- "property1": {
- "status": "ok",
- "latency_ms": 0,
- "required": true
}, - "property2": {
- "status": "ok",
- "latency_ms": 0,
- "required": true
}
}
}