Limits & errors

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

Base URL https://api.offendersearch.app

View as MarkdownCopy the whole reference for an LLM

Limits

Limit	Value	What happens at it
Pins start at zoom	13	Below it a view is answered as clusters.
Names start at zoom	15	Below it a pin has no `label`.
Lowest zoom answered	3	A wider view is answered at this zoom.
`zoom` parameter	0 to 22	Outside it: `422 invalid_zoom`.
Map tiles in one view	64	A wider box is answered at a lower zoom. It is not refused.
Pins in one response	300	A denser view is answered as clusters on a finer grid.
People inline on a many-people pin	10	Past it, use the groups route.
Group page size	1 to 100, default 50	Outside it: `422 invalid_page`.
Marker id and group id life	24 hours	`410 marker_expired` or `410 group_expired`.
Free re-open by `recordRef`	24 hours	After it, opening by reference is one record open again.
Signed photo link	1 hour	Open the record again for a new link.
Radius	0.1 to 100 miles	Outside it: `422 invalid_radius`.
Polygon points	3 to 200	Outside it: `422 invalid_shape`.
Route points	2 to 200	Outside it: `422 invalid_shape`.
Route buffer	0.05 to 5 miles	Outside it: `422 invalid_shape`.
Browser cache time	300 seconds	The `max-age` on a view.
Longest life of an `ETag`	12 hours	After it the same view is a new answer with new ids.
Distinct areas read for pins, for each account, each day	20,000	`429 map_sweep_limit`. See below.
The same, for each end user (`X-End-User`)	2,000	`429 map_end_user_limit`.
Map requests answered at the same moment	2 on each API server	`429 map_busy` with `Retry-After: 1`.

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 neighbourhood 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.

The error body

Every error has the same shape. Switch on detail.code. Show detail.message to a developer, not to an end user.

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.

Request errors

Code	Status	Cause	What to do
`invalid_bbox`	422	`bbox` 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_center`	422	`center` is not `lat,lng`, or it came without `radiusMiles`.	Send `center=lat,lng` together with `radiusMiles`.
`invalid_radius`	422	`radiusMiles` is not a number from 0.1 to 100.	Send a radius inside the range.
`invalid_zoom`	422	`zoom` is not a number from 0 to 22.	Send the map’s zoom, or leave it out.
`invalid_filter`	422	`housing` or `precision` has a value that is not listed.	Use `housed`, `homeless`, `incarcerated` for `housing`, and `street` or `any` for `precision`.
`invalid_format`	422	`format` is not `json` or `geojson`.	Send one of the two.
`invalid_detail`	422	`detail` is not `full` or `count`.	Send one of the two.
`invalid_page`	422	`page` is below 1, or `perPage` is not 1 to 100.	Send a page from 1 and a page size inside the range.
`invalid_shape`	422	The 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.

Access errors

Code	Status	Cause	What to do
—	401	The 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.
`map_not_enabled`	403	The Map API is off for this account.	Turn it on. See Turn it on. To build first, send `sandbox=true`.
`map_paused`	403	We have paused the Map API for this account.	Write to support@offendersearch.app.
`origin_not_allowed`	403	A 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

Code	Status	Cause	What to do
`unknown_marker`	404	The 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_group`	404	The group id is not one this account was given.	The same.
`marker_expired`	410	The marker id is older than 24 hours.	Request the view again for a new id. For saved links, keep the `recordRef`.
`group_expired`	410	The group id is older than 24 hours.	Request the view again for a new id.
`record_no_longer_listed`	410	The registry no longer lists the person. Not billed.	Remove the pin, and say the record is no longer listed.

Limit errors

Code	Status	Cause	What to do
`map_sweep_limit`	429	The 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_limit`	429	One end user has used their area limit for the day.	Tell that user. Other users are not affected.
`map_busy`	429	Too 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.
`overloaded`	429	The 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

Code	Status	Cause	What to do
`map_index_not_ready`	503	The map data is not ready to answer yet.	Retry shortly.
`map_unavailable`	503	The map could not be read just now. Nothing was charged.	Retry after the `Retry-After` header.
`map_not_configured`	503	The 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.

Code	Status	Cause	What to do
`minimum_not_accepted`	422	`acceptMinimum` was not `true`.	Send `{"acceptMinimum": true}`.
`payment_method_required`	402	There 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_failed`	402	The card was declined. Nothing was turned on and nothing was charged.	Fix or replace the card, then try again.
`business_account_required`	403	The account is a personal account.	Use a business account.
`admin_required`	403	The dashboard seat is not an admin of the account.	Ask an account admin to turn it on, or use a secret key.

Sex offender registry

Criminal records

Platform

Trust

By industry

By platform

By use case

More

Documentation

APIs

Build

Reference

Sex offender registry

Criminal records

Family safety

More searches

Learn

Compare

Company

Your record