Sex offender map API reference
Every endpoint and object, each linked to its request and response fields.
Livehttps://api.offendersearch.appSandboxhttps://sandbox.offendersearch.appNine endpoints and the objects they send and return. Each endpoint below links to its Request and Response tables, and each object to the one table that defines it; every other page links to the same tables, so a field is described in one place.
All nine take a secret key in X-API-Key. The seven map read routes (viewport, area, route, routes, groups, records and status) also take a map browser key from a site on that key’s list (see Access & keys); on the route routes a browser key also sends X-End-User. sandbox=true answers the viewport, area and route routes in test mode, and the ids a test-mode answer returns keep the groups and records routes in test mode. The opened record is the same object the search API returns: The Record object.
Sex offender map API endpoints
Every Map API route, with what it does. Each one opens its Request and Response tables: every field, its type, default and an example.
| Endpoint | What it does |
|---|---|
| GET /v1/map/viewport | Map view. What to draw for one map view: clusters, pins or named pins of registered sex offenders. Send the view as bbox, or as center with radiusMiles. One map request per answer, whatever the view holds; a 304, test mode and errors are free. |
| POST /v1/map/area | Drawn area. Everyone inside a drawn shape: a polygon, or a route with a buffer either side. The answer is the viewport answer for the shape's bounding box, limited to what is inside the shape, plus shape. One map request per answer; test mode and errors are free. An area answer carries no ETag. |
| POST /v1/map/route | Route. Exact counts and nameless pins along one route: within a corridor either side of a line, within a radius of each stop, or both, per leg and per stop. Billed as route units, each one map request; detail=count costs the same; a 304, test mode and errors are free. Never partial: a route is answered whole or refused with nothing charged. |
| POST /v1/map/routes | Routes in a batch. Up to 50 routes in one call, answered all or nothing: any refused route refuses the batch, with its routeIndex, and nothing is billed. Billed as the sum of the routes' units. Every marker shares one response, so a person near several routes is one record open. |
| GET /v1/map/groups/{groupId} | Group members. One page of the people behind a many-people pin or an approximate-area pin. One map request per page; test mode and errors are free. |
| GET /v1/map/records/{markerId} | Open a record. The complete record behind a marker or a saved reference. One record open per person per map response, at the account's rate ($0.035 by default): the same marker id again is free, and so is a reference within 24 hours of an open. record_no_longer_listed, test mode and errors are not billed. |
| GET /v1/map/status | Plan and usage. The Map API plan, rates, limits and this month's usage. Free, and it answers for an account whose Map API is off: it is how a client finds out that it is. |
| POST /v1/map/enable | Turn it on. Turn the Map API on. Any paying business account can, with a secret key or an account admin's dashboard session. The monthly minimum is charged to the card at that moment and covers the current calendar month; if the charge fails, nothing is turned on. On an account that is already on it changes nothing and charges nothing. |
| POST /v1/map/disable | Turn it off. Turn the Map API off. Free. The map routes stop within seconds; test mode keeps working. The month stays a minimum month, a minimum already paid is not refunded, and turning it on again in the same month charges nothing more. |
Sex offender map API objects
Every object the Map API returns, defined once. A field whose type is one of these links here.
| Object | What it is |
|---|---|
| MapBreakdown | Four counts of the people in a view or a cluster. They are not a split of the total: one person counts in street and in a housing number. A person whose registry states no housing status is in total and in none of the three housing counts. |
| MapCluster | A count for one grid cell, returned in clusters mode (zoom 3 to 12, and closer views holding more than 300 pins). Draw it as a circle with count inside. |
| MapMarker | One person at one exact street address, in markers[]. In pins mode (zoom 13 and 14) it is a position and nothing that identifies anyone. In markers mode (zoom 15 and closer) it also carries label, housingStatus, hasPhoto and registryState. A person with two mapped addresses has two pins; total counts that person once. |
| MapMember | One person behind a many-people pin or an approximate-area pin: in members[] of a groups response, and inline on a many-people pin at zoom 15 and closer. label, housingStatus and hasPhoto are present only when the group came from a view at zoom 15 or closer (named: true); otherwise a member is id and addressType only. |
| MapGroupPin | Several people at one exact street address, drawn as one pin in markers[]. Tell it apart from a single pin by id: null and a groupId. List the people with GET /v1/map/groups/{groupId}. |
| MapArea | People known only to the middle of a ZIP code, a city or a county, in areas[]. People in custody are always here, as are people without a fixed address whose registered address has no street number. An area is never drawn as an exact pin: draw it so it does not look like an address. |
| MapUnplaced | People in the states this view touches who have no mappable address. They are on a registry and they are not on the map: show the count next to the map so a short list of pins is not read as the whole list. The count is for whole states, not for the box. |
| MapGeoJson | The same answer as a GeoJSON FeatureCollection of points, returned with format=geojson and content type application/geo+json. It goes straight into a map library's GeoJSON source. A route answer with format: "geojson" has the same shape: one point per marker (kind: "marker"), group (kind: "group") and approximate area (kind: "area"), with the rest of the route answer under meta. |
| MapRouteStopInput | One stop in stops[] of a route request. A bare [lng, lat] pair is accepted too, and gets the id s1, s2, … by its position. |
| MapRouteLeg | The line between two stops, in legs[]. With fewer than two stops the whole line is one leg. Each person in the corridor counts on the leg of their nearest point of the line, so the leg counts add up to corridorTotal. |
| MapRouteStop | One stop, as answered, in stops[], in the order sent. |
| MapRouteMarker | One person at one exact street address near the route, in markers[]. A position, its place on the route and an id. Never a name, on any plan. |
| MapRouteGroup | Several people registered at one exact street address near the route, as one pin in groups[]. The people behind it open with GET /v1/map/groups/{groupId} (one map request per page, no names). |
| MapRouteArea | People mapped only to the centre of a ZIP code, city or county, in approximate.areas[]. Their distance to the route is not known, so they are listed here and never counted in total. |
| MapRouteProfile | The limits of one route profile, as GET /v1/map/status reports them under routes.profiles. |
| MapBilling | Whether this record open was charged, and why. Every GET /v1/map/records/{markerId} answer carries it. |
| MapError | 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. |