Offender Map API · v1.0.0

Limits & errors

Every limit with its number, and every error code with its cause and fix.

Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.app

Limits

LimitValueWhat happens at it
Pins start at zoom13Below it a view is answered as clusters.
Names start at zoom15Below it a pin has no label.
Lowest zoom answered3A wider view is answered at this zoom.
zoom parameter0 to 22Up to 24 is accepted and answered at 22. Below 0 or above 24: 422 invalid_zoom.
Map tiles in one view64A wider box is answered at a lower zoom. It is not refused.
Pins in one response300A denser view is answered as clusters on a finer grid.
People inline on a many-people pin10Past it, use the groups route.
Group page size1 to 100, default 50Outside it: 422 invalid_page.
Marker id and group id life24 hours410 marker_expired or 410 group_expired.
Free re-open by recordRef24 hoursAfter it, opening by reference is one record open again.
Signed photo link7 daysAny number of loads. Open the record again for a new link.
Radius0.1 to 100 milesOutside it: 422 invalid_radius.
Polygon points3 to 200Outside it: 422 invalid_shape.
Route points2 to 200Outside it: 422 invalid_shape.
Route buffer0.05 to 5 milesOutside it: 422 invalid_shape.
Browser cache time300 secondsThe max-age on a view.
Longest life of an ETag12 hoursAfter it the same view is a new answer with new ids.
Distinct areas read for pins, for each account, each day20,000429 map_sweep_limit. See below.
The same, for each end user (X-End-User)2,000429 map_end_user_limit.
Map requests answered at the same moment2 on each API server429 map_busy with Retry-After: 1.
Different routes checked by one end user each day20 by default429 map_end_user_route_limit. See below.
Records opened each day, for the account or one end userNo limit by default429 map_open_limit when a limit is set. See below.
Route length, stops, corridor and radius15 miles walking, 60 by busSee Routes, stops and corridors.

Your account’s own values for the zoom thresholds, the pin cap and the area limits are in GET /v1/map/status.

The daily area limit

Pins are counted by area. The map is divided into fixed squares, the map tiles of zoom 14. Each day an account may read pins for 20,000 different squares.

  • Only different squares count. Looking at the same neighborhood a thousand times in a day counts its squares once.
  • Only pins count. Cluster views are never limited, and they keep working after the limit is reached. Test mode is never counted.
  • It resets each day, at midnight UTC.
  • Each end user has a share. When you send X-End-User, that person may read pins for 2,000 different squares a day. One person paging across a whole state is then stopped with map_end_user_limit before the account’s limit is touched.
  • Normal use does not reach it. People browsing a map look at a small number of places. The limit stops a copy of every pin in the country being taken through the map.

To have either number raised, write to support@offendersearch.app with your account, what the map is for and the number you need. Both are set for each account.

Daily limits on record opens and routes

Three more daily limits can be set for each account, by us, on request. Each counts different things in a UTC day and resets at 00:00 UTC. GET /v1/map/status returns the account’s values under limits; 0 means no limit.

LimitStatus fieldDefaultPast it
Different records the account opens in a daylimits.recordOpensPerDayOff429 map_open_limit on the records route
Different records one end user (X-End-User) opens in a daylimits.endUserOpensPerDayOff429 map_open_limit for that user
Different routes one end user checks in a daylimits.endUserRoutesPerDay20429 map_end_user_route_limit for that user
  • Only different records count. Opening a record already opened today is never refused and never counts twice.
  • Only different routes count. A route already checked today can be checked again, with pins or as a count.
  • Nothing is charged for a refused call. The body carries budget and retryAfterSeconds.
  • The per-end-user limits need X-End-User. Send it on the records route as well as the route routes, so an open limit for each user can apply.
  • For a platform, these let you give each of your users a share of the account. See Platform integration.

The error body

Every coded error has the same shape. Switch on detail.code. Show detail.message to a developer, not to an end user. A 401, a 402, and an area body with wrongly typed fields carry a plain detail instead, with no code; switch on the status for those.

403 Forbidden
{
  "detail": {
    "code": "map_not_enabled",
    "message": "The Map API is not turned on for this account. …",
    "dashboardUrl": "https://offendersearch.app/dashboard/map-api",
    "docsUrl": "https://offendersearch.app/docs/map/turn-it-on"
  }
}

Some errors add dashboardUrl, docsUrl, billingUrl or retryAfterSeconds. No error response is billed.

The map error body: the MapError object

The error body of every /v1/map/* route, with three exceptions that carry the Error object instead: a missing or invalid key (401, a plain detail string), an account with no active subscription and no active free trial (402, a plain detail string), and a POST /v1/map/area or route body whose fields have the wrong JSON types (422, the standard validation detail list). Switch on detail.code; show detail.message to a developer. No error response is billed.

FieldTypeDescription
detail
objectThe error.
detail.code
string
one of "invalid_bbox", "invalid_center", "invalid_radius", "invalid_zoom", "invalid_filter", "invalid_format", "invalid_detail", "invalid_page", "invalid_shape", "invalid_route", "invalid_path", "invalid_polyline", "invalid_profile", "invalid_measure", "invalid_corridor", "invalid_stops", "route_too_long", "route_too_many_points", "route_too_many_stops", "route_batch_too_large", "route_too_dense", "route_too_many_people", "end_user_required", "map_not_enabled", "map_paused", "origin_not_allowed", "unknown_marker", "unknown_group", "marker_expired", "group_expired", "record_no_longer_listed", "map_sweep_limit", "map_end_user_limit", "map_end_user_route_limit", "map_open_limit", "map_busy", "overloaded", "map_index_not_ready", "map_unavailable", "map_not_configured", "minimum_not_accepted", "payment_method_required", "payment_failed", "business_account_required", "admin_required"
The stable code to switch on. Every code, with its status, cause and fix, is in the tables on this page.
detail.message
stringA plain sentence saying what happened and what to do.
detail.retryAfterSeconds
integerSeconds to wait before retrying; the same as the Retry-After header. On map_busy, map_sweep_limit, map_end_user_limit, map_end_user_route_limit, map_open_limit and overloaded.
detail.budget
integerThe daily limit that was reached. On map_sweep_limit, map_end_user_limit, map_end_user_route_limit and map_open_limit.
detail.counts
objectOn route_too_many_people: the route's exact total, corridorTotal, stopsTotal, breakdown, legs, stops, approximate.count and units, so you can show the numbers and switch to detail=count.
detail.maxMarkers
integerOn route_too_many_people: the most pins one answer carries.
detail.routeIndex
integerOn a POST /v1/map/routes refusal: the route it is about, from 0.
detail.dashboardUrl
stringWhere to fix it in the dashboard. On map_not_enabled and origin_not_allowed.
detail.docsUrl
stringThe page that explains it. On map_not_enabled.
detail.billingUrl
stringThe dashboard billing page. On payment_method_required and payment_failed.

Request errors

CodeStatusCauseWhat to do
invalid_bbox422bbox is missing or is not west,south,east,north, or it was sent together with center.Send four numbers in degrees: south below north, west and east within ±180 and different. Send bbox or center, not both.
invalid_center422center is not lat,lng, or it came without radiusMiles.Send center=lat,lng together with radiusMiles.
invalid_radius422radiusMiles is not a number from 0.1 to 100.Send a radius inside the range.
invalid_zoom422zoom is not a number, or is below 0 or above 24.Send the map’s zoom, or leave it out.
invalid_filter422housing or precision has a value that is not listed.Use housed, homeless, incarcerated for housing, and street or any for precision.
invalid_format422format is not json or geojson.Send one of the two.
invalid_detail422detail is not full or count.Send one of the two.
invalid_page422page is below 1, or perPage is not 1 to 100.Send a page from 1 and a page size inside the range.
invalid_shape422The body has both or neither of polygon and route, the wrong number of points, or a buffer outside the range.Send one shape, inside the limits above.

Route errors: route corridor and stop codes

These come from POST /v1/map/route and POST /v1/map/routes. A refused route is never charged. In a batch, routeIndex names the route that refused it.

CodeStatusCauseWhat to do
invalid_route422The route is not a JSON object, or a batch has no routes.Send a route object; send 1 to 50 in a batch.
invalid_path422More than one of path, points and polyline; a point that is not [lng, lat]; a line of one point; a corridor with no line; or a route that crosses the date line.Send one line, longitude first.
invalid_polyline422The polyline does not decode, or decodes off the globe.Check polylinePrecision: 5 for Google, 6 for Mapbox, OSRM and Valhalla.
invalid_profile422profile is not walk or bus.Send one of the two.
invalid_measure422measure is not corridor, stops or both.Send one of the three, or leave it out.
invalid_corridor422corridorMiles is outside 0.02 to 0.25.Send a corridor inside the range.
invalid_radius422stopRadiusFeet or parcelAllowanceFeet is outside its range.See the limits above.
invalid_stops422A stop is not {id, lng, lat} or [lng, lat], an id is used twice, or stops are measured with no stops.Fix the stop, or measure the corridor only.
invalid_detail, invalid_format, invalid_filter422As on the viewport route. A batch answers in json only.Send an accepted value.
route_too_long422Longer than the profile allows, or touching more map area than one call reads.Split the route into shorter routes.
route_too_many_points422More than 50,000 points, or more than 2,000 after simplifying.Split the route.
route_too_many_stops422More stops than the profile allows.Split the route, or use bus.
route_batch_too_large422More than 50 routes in a batch.Send at most 50 per call.
route_too_dense422The route passes through more registered addresses than one call counts exactly.Split the route, or narrow the corridor.
route_too_many_people422More than 300 pins with detail=full. counts holds the exact counts.Show the counts, send detail=count, or split the route.
end_user_required422A map browser key sent no X-End-User.Send any stable id for your user, such as a hashed user id.
map_end_user_route_limit429This end user has checked 20 different routes today (the default).A route already checked today can be checked again. Other users are not affected. It resets at 00:00 UTC.
map_unavailable503The route could not be read just now. No result, nothing charged.Retry after the Retry-After header.

Access errors

CodeStatusCauseWhat to do
—401The key is missing or wrong, or a map browser key was used on a route that does not accept one.Send a valid key in X-API-Key. Use a secret key, from your server, for other routes.
—402The account has no active subscription and no active free trial.Add a payment method in the dashboard under Billing.
map_not_enabled403The Map API is off for this account.Turn it on. See Turn it on. To build first, send sandbox=true.
map_paused403We have paused the Map API for this account.Write to support@offendersearch.app.
origin_not_allowed403A map browser key was used from a site that is not on its list.Add the site to the key, or call from your server with a secret key. See Access & keys.

Id errors

CodeStatusCauseWhat to do
unknown_marker404The marker id or reference is not one this account was given.Use ids from your own responses, with a key of the same account.
unknown_group404The group id is not one this account was given.The same.
marker_expired410The marker id is older than 24 hours.Request the view again for a new id. For saved links, keep the recordRef.
group_expired410The group id is older than 24 hours.Request the view again for a new id.
record_no_longer_listed410The registry no longer lists the person. Not billed.Remove the pin, and say the record is no longer listed.

Limit errors

CodeStatusCauseWhat to do
map_sweep_limit429The account has used its area limit for the day.Clusters still work: show them and ask the user to try pins tomorrow. If normal use reaches it, ask us to raise it.
map_end_user_limit429One end user has used their area limit for the day.Tell that user. Other users are not affected.
map_end_user_route_limit429One end user has checked their daily number of different routes.Routes already checked today still answer. Other users are not affected.
map_open_limit429A daily limit on record opens is set and reached, for the account or one end user.Records already opened today still open. It resets at 00:00 UTC.
map_busy429Too many map requests at the same moment.Retry after the Retry-After header, which is 1 second. Wait for the map to settle and cancel requests you no longer need.
overloaded429The service is at capacity.Retry after the Retry-After header.

A 429 here is not a charge and not a ban. Wait for the time in Retry-After and send the request again.

Service errors

CodeStatusCauseWhat to do
map_index_not_ready503The map data is not ready to answer yet.Retry shortly.
map_unavailable503The map could not be read just now. Nothing was charged.Retry after the Retry-After header.
map_not_configured503The Map API is not available on this server.Retry. If it continues, write to us.

Turn-on errors

These come only from POST /v1/map/enable and POST /v1/map/disable.

CodeStatusCauseWhat to do
minimum_not_accepted422acceptMinimum was not true.Send {"acceptMinimum": true}.
payment_method_required402There is no card on the account, or it is on the free trial.Add a payment method in the dashboard under Billing, then try again.
payment_failed402The card was declined. Nothing was turned on and nothing was charged.Fix or replace the card, then try again.
business_account_required403The account is a personal account.Use a business account.
admin_required403The dashboard seat is not an admin of the account.Ask an account admin to turn it on, or use a secret key.

Product overview