Beehive Maps API (1.0.0)

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.

Authentication

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.

Key types

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.

Rate limits

Two independent limits apply to every request:

  • a per-key limit, shared across all services that key can reach
  • a per-service limit, specific to the service being called

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.

Billable units

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.

Errors

Every error shares one envelope with a stable, machine-readable code. Match on code, never on message.

Attribution

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.

Directions

Routing, matrices, matching and optimization. Powered by OSRM.

Route between two or more waypoints

Returns one or more routes with turn-by-turn steps.

Scope: directions:read · Units: 1 + max(0, waypoints - 2)

Authorizations:
bearerAuth
query Parameters
coordinates
required
string
Example: coordinates=28.2833,-15.4167;28.3228,-15.3875

Semicolon-separated lon,lat pairs — longitude first, matching GeoJSON. Reversing them is the most common integration bug; a coordinate outside the covered region is usually a swapped pair.

profile
string
Default: "car"
Value: "car"

Travel mode. Only car is available at launch.

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. polyline6 is the most compact; geojson is the easiest to draw directly on a map.

overview
string
Default: "simplified"
Enum: "full" "simplified" "false"
annotations
string

Comma-separated extras, e.g. duration,distance,speed.

Responses

Response samples

Content type
application/json
{
  • "routes": [
    ],
  • "waypoints": [
    ],
  • "meta": {
    }
}

Duration and distance matrix

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

Authorizations:
bearerAuth
query Parameters
coordinates
required
string
Example: coordinates=28.2833,-15.4167;28.3228,-15.3875

Semicolon-separated lon,lat pairs — longitude first, matching GeoJSON. Reversing them is the most common integration bug; a coordinate outside the covered region is usually a swapped pair.

sources
string
Example: sources=0;1

Indices into coordinates to use as origins. Omit for all.

destinations
string
Example: destinations=2;3

Indices into coordinates to use as destinations. Omit for all.

annotations
string
Default: "duration,distance"
Enum: "duration" "distance" "duration,distance"

Responses

Response samples

Content type
application/json
{
  • "durations": [
    ],
  • "distances": [
    ],
  • "sources": [
    ],
  • "destinations": [
    ],
  • "meta": {
    }
}

Snap coordinates to the road network

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)

Authorizations:
bearerAuth
query Parameters
coordinates
required
string
Example: coordinates=28.2833,-15.4167;28.3228,-15.3875

Semicolon-separated lon,lat pairs — longitude first, matching GeoJSON. Reversing them is the most common integration bug; a coordinate outside the covered region is usually a swapped pair.

radius
number <= 5000
Default: 100

Maximum search radius in metres.

Responses

Response samples

Content type
application/json
{
  • "waypoints": [
    ],
  • "meta": {
    }
}

Match a GPS trace to the road network

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)

Authorizations:
bearerAuth
query Parameters
coordinates
required
string
Example: coordinates=28.2833,-15.4167;28.3228,-15.3875

Semicolon-separated lon,lat pairs — longitude first, matching GeoJSON. Reversing them is the most common integration bug; a coordinate outside the covered region is usually a swapped pair.

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"

Responses

Response samples

Content type
application/json
{
  • "matchings": [
    ],
  • "tracepoints": [
    ],
  • "meta": {
    }
}

Order waypoints into the shortest round trip

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²

Authorizations:
bearerAuth
query Parameters
coordinates
required
string
Example: coordinates=28.2833,-15.4167;28.3228,-15.3875

Semicolon-separated lon,lat pairs — longitude first, matching GeoJSON. Reversing them is the most common integration bug; a coordinate outside the covered region is usually a swapped pair.

roundtrip
boolean
Default: true

Return to the first waypoint.

source
string
Default: "first"
Enum: "any" "first"
destination
string
Default: "any"
Enum: "any" "last"

Responses

Response samples

Content type
application/json
{
  • "trips": [
    ],
  • "waypoints": [
    ],
  • "meta": {
    }
}

Geocoding

Forward, reverse and autocomplete search. Powered by Photon.

Find places by name or address

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

Authorizations:
bearerAuth
query Parameters
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 minLon,minLat,maxLon,maxLat.

lang
string
Default: "en"
layer
string
Example: layer=city,street,house

Restrict to feature types, comma-separated.

Responses

Response samples

Content type
application/geo+json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "meta": {
    }
}

Find what is at a coordinate

Reverse geocoding.

Scope: geocode:reverse · Units: 1

Authorizations:
bearerAuth
query Parameters
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"

Responses

Response samples

Content type
application/geo+json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "meta": {
    }
}

Type-ahead place search

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

Authorizations:
bearerAuth
query Parameters
q
required
string [ 1 .. 200 ] characters
limit
integer [ 1 .. 20 ]
Default: 5
lat
number
lon
number
lang
string
Default: "en"

Responses

Response samples

Content type
application/geo+json
{
  • "type": "FeatureCollection",
  • "features": [
    ],
  • "meta": {
    }
}

Tiles

Vector tiles, styles, glyphs and static images.

Start a map session

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

Authorizations:
bearerAuth
Request Body schema: application/json
optional
style
string
Default: "road"
Enum: "road" "dark"

Style this session will render. Must be within the key's scopes.

Responses

Request samples

Content type
application/json
{
  • "style": "road"
}

Response samples

Content type
application/json
{
  • "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": {
    }
}

Fetch a vector tile

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

path Parameters
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
query Parameters
token
required
string

Tile session token.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Fetch a MapLibre style

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

path Parameters
style
required
string
Enum: "road" "dark"
query Parameters
token
required
string

Responses

Response samples

Content type
application/json
{ }

Fetch glyphs

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

path Parameters
fontstack
required
string
Example: Noto Sans Regular
range
required
string
Example: 0-255
query Parameters
token
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Render a static map image

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

Authorizations:
bearerAuth
path Parameters
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"
query Parameters
marker
Array of strings

Repeatable. lon,lat or lon,lat,colour.

path
string

Encoded polyline to draw, e.g. a route geometry.

retina
boolean
Default: false

Render at 2× pixel density.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Usage

Programmatic access to your own consumption.

Your own usage

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

Authorizations:
bearerAuth
query Parameters
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"

key covers only the calling key. organization covers every key in the org and requires the usage:read:org scope.

Responses

Response samples

Content type
application/json
{
  • "from": "2019-08-24T14:15:22Z",
  • "to": "2019-08-24T14:15:22Z",
  • "granularity": "string",
  • "total_units": 0,
  • "by_service": {
    },
  • "series": [
    ],
  • "quota": {
    },
  • "meta": {
    }
}

System

Health and metadata.

Liveness

Is the gateway process up. No authentication.

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Readiness, including upstreams

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.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "map_release": "string",
  • "checks": {
    }
}