Map API sandbox server & test keys

Every Map API route with a test key and no live key: fixed made-up people, never metered.

Sandboxhttps://sandbox.offendersearch.appLivehttps://api.offendersearch.app

View as MarkdownWhole product as one Markdown fileOpenAPI

Map API test keys: create one in the dashboard

The Map API sandbox server is the Map API on a separate server, for building with a test key and no live key at all. Every route runs there with no plan to turn on and nothing metered, and every request is in test mode. Already calling the live API? Add sandbox=true instead: see Test mode. Both draw the same made-up people.

In the dashboard, open Developers → API keys.
Choose Create test key. Test keys are for business accounts and need no subscription.
Copy the key. Test keys begin os_test_. Like a live key, the full secret is shown once, so put it in your secrets store straight away.

One test key works on every API’s sandbox. Each key in the list is labelled Test · Sandbox or Live, with the base URL it works on. Send it in the same X-API-Key header the live API uses. An account holds up to 3 active test keys and can create 10 a day. A revoked test key stops working on the sandbox within a few minutes.

Map API sandbox base URL vs live and test mode

	Sandbox	Production
Base URL	https://sandbox.offendersearch.app	https://api.offendersearch.app
Key prefix	os_test_	os_live_
Data	The made-up test-mode people, around eight cities	Live registry data, once the Map API is turned on
Billing	Never billed, never recorded to usage	Your plan’s prices
`sandbox` field	`true` on every response	Absent
`X-Offendersearch-Environment`	`sandbox` on every response	Absent

Each key works on its own server only, so a mixed-up configuration is caught on the first request rather than after a release. A test key sent to the live API, or a live key sent to the sandbox, is refused with 401 and a detail message that says so:

401 — a test key sent to the live API

{
  "detail": "This is a test key (os_test_…). Test keys work only on the sandbox at https://sandbox.offendersearch.app, which answers with sample data. To search real records, send a live key (os_live_…) to https://api.offendersearch.app."
}

401 — a live key sent to the sandbox

{
  "detail": "This is a live key. The sandbox at https://sandbox.offendersearch.app accepts test keys (os_test_…) only — create one in the dashboard under Developers → API keys. Send live keys to https://api.offendersearch.app."
}

A revoked test key gets 401 with: “This test key has been revoked. Create a new test key in the dashboard under Developers → API keys.”

Each test key can send 60 requests a minute and 2,000 a day, and one IP address 120 a minute, across every API on the sandbox. Past a limit the sandbox answers 429 with a Retry-After header. See Sandbox rate limits.

Map API sandbox scenarios

Every Map API route runs on the sandbox, with no plan to turn on and nothing metered. It draws the same made-up people as test mode on the live API, around Columbus, Cleveland, Cincinnati, Chicago, New York, Los Angeles, Houston and Seattle. You do not add sandbox=true on the sandbox: every request there is test mode. The counts below are fixed.

Send	What comes back
GET /v1/map/viewport bbox=-83.20,39.85,-82.80,40.10	A city view: clusters. Zoom 11 over Columbus, OH: mode clusters, 529 people in 63 clusters.
GET /v1/map/viewport center=39.9612,-82.9988 radiusMiles=1	One mile around a point: named pins. Zoom 15: mode markers, exactly 37 people within the mile (withinRadius 37), 15 named pins plus one approximate-area pin, each with distanceMiles.
GET /v1/map/viewport bbox=-83.0060,39.9665,-83.0025,39.9690	Many people at one address. One street-precision pin holding 14 people (a groupId, no inline members); GET /v1/map/groups/{groupId} pages through the 14, all housingStatus homeless.
GET /v1/map/viewport bbox=-83.0130,39.9680,-83.0100,39.9700	An approximate-area pin. No street pins; one area pin (precision zip, label 43215) for 9 people whose registry gives only a ZIP code.
POST /v1/map/area	A drawn polygon. shape polygon: 22 people inside, 9 pins (the 14-person address is one of them).
GET /v1/map/records/{markerId} markerId from any named pin of map-radius-pins	Open the record behind a pin. The complete record (a 'Sample …' person, Sampleville, ZIP 00000), a recordRef that opens it again later, and billing {billed: false, reason: sandbox}.
POST /v1/map/route	A walking route with a stop. 2.118 miles, 4 route units: 2 people within the 0.1-mile corridor, 1 within 1,000 feet of stop s1, and 9 more placed only to a ZIP (approximate.count 9).
POST /v1/map/routes	Two routes in one call. shape routes, 8 units, uniquePeople 2 (the same two people on both routes).
GET /v1/map/status	Plan and usage. enabled true, sandbox true, the published rates, and zero usage this month.
POST /v1/map/enable	Turning it on or off. The sandbox map is always on: enable and disable both answer the status with changed false, and nothing is charged.

GET /v1/map/viewport — sandbox

curl "https://sandbox.offendersearch.app/v1/map/viewport?bbox=-83.20,39.85,-82.80,40.10" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY"

Map API sandbox examples in cURL, Node and Python

A city view: clusters, called three ways. No sandbox=true is needed on the sandbox server. Export your test key as OFFENDERSEARCH_TEST_KEY first.

curl "https://sandbox.offendersearch.app/v1/map/viewport?bbox=-83.20,39.85,-82.80,40.10" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY"

Postman collection for the Map API sandbox

One collection covers every API’s sandbox, with a folder per API, ready to import into Postman or Insomnia. The Offender Map API folder has one request for every scenario on this page. Set {{apiKey}} to your test key; {{baseUrl}} is preset to the sandbox. A request that needs an id from an earlier response uses a variable for it: {{markerId}}.

Download the sandbox collection (JSON)

Postman: Import, then drop the file. Insomnia: Import, then From file.

Move the Map API from the sandbox to production

The sandbox and the live API differ only in the base URL and the key. Keep both in configuration, not in code, and going live is a configuration change:

.env

# Sandbox
OFFENDERSEARCH_BASE=https://sandbox.offendersearch.app
OFFENDERSEARCH_KEY=os_test_…

# Production — change these two values and nothing else
OFFENDERSEARCH_BASE=https://api.offendersearch.app
OFFENDERSEARCH_KEY=os_live_…

Create a live key on the same Developers → API keys page.
Remove any branch that reads sandbox. The field does not exist on live.
Turn the Map API on for the live account: see Turn it on. Live map requests and record opens are billed; see Billing.
For a browser map, create a map browser key for your sites: see Access & keys.