Beta
API reference
Rana's own web services for maps, routing, roads, geocoding and places in Nigeria.
Version 1.0.0-beta. Server: https://maps-api.ranamaps.com (Customer API).
Operations
GET /v1/key Beta
Describes the key that calls, its organisation's plan and limits. Free; counts no usage.
POST /v1/directions/route Beta
A route from an origin to a destination, with optional waypoints and alternatives.
POST /v1/directions/matrix Beta
Distance and time from each origin to each destination. Up to 100 cells; usage counts one unit per cell.
POST /v1/roads/snap Beta
Snaps a GPS trace (up to 100 points) to the roads most likely travelled, with the distance along them.
GET /v1/geocode/reverse Beta
Street, area, ward, city, LGA and state for a point.
GET /v1/geocode Alpha
Points for a written place, street or area name. Alpha; thin outside Lagos.
GET /v1/places/autocomplete Alpha
Place, street, stop and area suggestions as a person types. Alpha; thin outside Lagos.
GET /v1/places/nearby Alpha
Verified places within a radius, nearest first. Alpha.
GET /v1/places/{place_id} Alpha
One verified place with its street, gates (status and hours) and approved photos. Alpha.
GET /v1/static Beta
A PNG or WebP picture of the map, with optional markers and one path. Cached at Cloudflare for a day.
POST /v1/telemetry Beta
SDK health events (the SDKs send these). Kept as daily counts; never location, viewport or user ids. Counts no usage.
Keys
| Scheme | Sent as | Notes |
|---|---|---|
| RanaKeyHeader | X-Rana-Key: … | Preferred. A public key (pk_live_…) in web pages and apps, a secret key (sk_live_…) on servers. |
| RanaKeyQuery | ?key=… | Allowed, but the header keeps keys out of URLs and logs. If both are sent and differ, the request is refused with conflicting_keys. |
Response headers
| Header | Meaning |
|---|---|
Rana-Request-Id | A random id for this request. Quote it to support. |
Rana-Stability | The label of the endpoint that answered. |
X-RateLimit-Limit | Requests (or matrix cells) allowed per minute for this organisation and product group. |
X-RateLimit-Remaining | Requests (or matrix cells) left in the current minute. |
Retry-After | Seconds to wait before trying again. Sent with 429 and 503. |
Error responses
| Response | When |
|---|---|
| BadRequest | The request is not valid (invalid_request, invalid_body, conflicting_keys, too_many_cells, too_many_points). |
| Unauthorized | No usable key (missing_key, malformed_key, unknown_key). |
| Forbidden | The key may not be used here (revoked, organisation_suspended, client_not_allowed, no_client_identity, secret_key_in_browser, scope_not_allowed). |
| NotFound | No such resource (not_found). |
| TooManyRequests | Over a limit (rate_limited, daily_limit_reached, spending_cap_reached). |
| InternalError | Our fault (internal_error). |
| Unavailable | Routing or search is busy or down (upstream_unavailable). |
| Timeout | The answer took too long (timeout). |
Every error code is explained on the errors page.
Schemas
Point
A point in WGS 84.
| Field | Type | Required | Notes |
|---|---|---|---|
lat | number | yes | |
lng | number | yes |
Metres
A distance in whole metres.
Type: integer
Seconds
A duration in whole seconds.
Type: integer
Polyline6
An encoded polyline at precision 6.
Type: string
GeoJsonLineString
| Field | Type | Required | Notes |
|---|---|---|---|
type | "LineString" | yes | |
coordinates | array | yes |
Attribution
Type: string
Always © Rana Maps © OpenStreetMap
Plan
trial is free with daily limits; payg bills every unit; starter and business are subscriptions with overage.
Type: string
Values: trial, payg, starter, business, custom
KeyInfo
| Field | Type | Required | Notes |
|---|---|---|---|
organisation_id | string | yes | |
key | object | yes | |
plan | Plan | yes | |
limits | object | yes | |
attribution | Attribution | yes |
Location
A point, or one of our place ids. A destination place routes to its open gate.
Avoid
Type: array
Line
polyline6 by default; a GeoJSON LineString with ?geometry=geojson.
RouteRequest
| Field | Type | Required | Notes |
|---|---|---|---|
origin | Location | yes | |
destination | Location | yes | |
waypoints | array | ||
mode | Mode | ||
alternatives | boolean | Up to two more routes. Ignored with waypoints. | |
avoid | Avoid | ||
departure_time | string | Used for gate opening hours. No live traffic. |
Step
| Field | Type | Required | Notes |
|---|---|---|---|
instruction | string | yes | |
maneuver | string,null | yes | For example turn-left, keep-right, roundabout, depart, arrive. |
distance_m | Metres | yes | |
duration_s | Seconds | yes | |
street_names | array | yes | |
location | Point | yes | |
geometry | Line | yes |
Leg
| Field | Type | Required | Notes |
|---|---|---|---|
distance_m | Metres | yes | |
duration_s | Seconds | yes | |
start | Point | yes | |
end | Point | yes | |
steps | array | yes |
Route
| Field | Type | Required | Notes |
|---|---|---|---|
distance_m | Metres | yes | |
duration_s | Seconds | yes | |
geometry | Line | yes | |
legs | array | yes |
RouteResponse
| Field | Type | Required | Notes |
|---|---|---|---|
routes | array | yes | |
attribution | Attribution | yes |
MatrixRequest
| Field | Type | Required | Notes |
|---|---|---|---|
origins | array | yes | |
destinations | array | yes | |
mode | Mode | ||
avoid | Avoid |
MatrixCell
| Field | Type | Required | Notes |
|---|---|---|---|
distance_m | integer,null | yes | |
duration_s | integer,null | yes |
MatrixResponse
| Field | Type | Required | Notes |
|---|---|---|---|
rows | array | yes | |
attribution | Attribution | yes |
SnapRequest
| Field | Type | Required | Notes |
|---|---|---|---|
points | array | yes | |
mode | string | ||
interpolate | boolean | Also return the points along the road between the snapped ones. |
SnapResponse
| Field | Type | Required | Notes |
|---|---|---|---|
points | array | yes | |
distance_m | Metres | yes | |
geometry | Line | yes | |
attribution | Attribution | yes |
ReverseGeocodeResponse
| Field | Type | Required | Notes |
|---|---|---|---|
street | string,null | yes | |
street_source | string,null | yes | |
area | string,null | yes | Suburb or neighbourhood. |
ward | string,null | yes | |
city | string,null | yes | |
lga | string,null | yes | Local government area. |
state | string,null | yes | |
country | string,null | yes | |
formatted | string,null | yes | |
attribution | Attribution | yes |
GeocodeResponse
| Field | Type | Required | Notes |
|---|---|---|---|
results | array | yes | |
attribution | Attribution | yes |
PlaceKind
Type: string
Values: unknown, fuel, bank, worship, education, health, lodging, market, food, shop, service, government, office, leisure, other
AutocompleteResponse
| Field | Type | Required | Notes |
|---|---|---|---|
suggestions | array | yes | |
attribution | Attribution | yes |
NearbyResponse
| Field | Type | Required | Notes |
|---|---|---|---|
results | array | yes | |
attribution | Attribution | yes |
Gate
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
role | string | yes | main or side |
point | Point | yes | |
status | string | yes | Now, in Lagos time, from the gate's hours. |
hours | string,null | yes | HH:MM-HH:MM, Lagos time. |
PlaceDetails
| Field | Type | Required | Notes |
|---|---|---|---|
place_id | string | yes | |
name | string | yes | |
aliases | array | yes | |
kind | string | yes | |
point | Point | yes | |
street | string,null | yes | |
house_number | string,null | yes | |
how_to_find | string,null | yes | |
gates | array | yes | |
photos | array | yes | |
updated_at | string,null | yes | |
attribution | Attribution | yes |
Mode
transit answers with no routes for now.
Type: string
Values: car, okada, keke, bicycle, walk, transit
ErrorCode
A stable code. Clients branch on it. New codes may be added; existing ones never change within v1.
Type: string
Values: invalid_request, invalid_body, conflicting_keys, too_many_cells, too_many_points, missing_key, malformed_key, unknown_key, revoked, organisation_suspended, client_not_allowed, no_client_identity, secret_key_in_browser, scope_not_allowed, not_found, rate_limited, daily_limit_reached, spending_cap_reached, internal_error, upstream_unavailable, timeout
Error
| Field | Type | Required | Notes |
|---|---|---|---|
error | ErrorCode | yes | |
message | string | yes | Plain English for the developer. Wording can change; do not parse it. |
docs | string | yes | Link to the code's entry on the errors page. |
details | Extra detail for some codes, for example the failing fields of invalid_body. |
Map data answers carry "attribution": "© Rana Maps © OpenStreetMap".