Offendersearch
Start free
Map API Reference

Open a record

The record route, when an open is charged, marker id life, and saved links.

Base URL https://api.offendersearch.app
View as MarkdownCopy the whole reference for an LLM

The request

GET /v1/map/records/{markerId} returns the complete record behind a marker. It accepts a marker id, mk_…, or a saved reference, mr_….

GET /v1/map/records/{markerId}
curl https://api.offendersearch.app/v1/map/records/mk_Zb3… \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
200 OK
{
  "record": { "…the same record object POST /v1/search returns…" },
  "recordRef": "mr_k2P…",
  "billing": {
    "billed": true,
    "unit": "map_record_open",
    "reason": "first_open_of_this_marker"
  },
  "notice": "A pin shows a registered address, not a person's current location."
}
FieldMeaning
recordThe same record object POST /v1/search returns. See The Record object.
recordRefA lasting reference to this record, mr_…, for bookmarks and shared links.
billing.billedtrue when this call was charged as a record open.
billing.reasonWhy. For example first_open_of_this_marker or marker_already_opened.
noticeA sentence to show with the record.

When a record open is charged

A record open is the complete record behind one marker. Opening the same marker again is free. A new map request returns new marker ids, so opening that person from the new result is a new charge.

  • One charge for each person in each map response. Opening a marker for the first time is one record open, $0.015.
  • The same marker id again is free. Close the panel, open it again, reload the page: no charge. The response says "reason": "marker_already_opened".
  • Two pins of one person are one charge. A person with a home pin and a work pin in the same response is charged once.
  • A new map response gives new ids. Every viewport or groups response carries new marker ids. Opening the same person from the new response is a new charge.
  • A 304 gives no new ids. An unchanged view keeps the ids you already have, so re-opening from it stays free.

To keep opens free while a person browses, keep the marker ids from the response you drew and reuse them. Do not call the viewport route again just to open a record.

How long ids last

Marker ids and group ids work for 24 hours, and only for the account they were issued to. After that the route answers 410 marker_expired or 410 group_expired. Request the view again for new ids.

Do not store a marker id in a database or a link. Store the recordRef.

Saved links: recordRef

Every opened record comes with a recordRef. It does not expire. Put it in a bookmark, a shared link or your own database, and open it later with the same route.

GET /v1/map/records/{markerId}
curl https://api.offendersearch.app/v1/map/records/mr_k2P… \
  -H "X-API-Key: $OFFENDERSEARCH_KEY"
  • Opening by reference is one record open. It is then free for 24 hours.
  • A record you just opened from a marker is also free by its reference for 24 hours.
  • A reference works only for the account it was issued to.

Photos

Photo links on hosted photos are signed. A link works in an <img> tag for one hour. Use it as it is, and do not store it: open the record again for a new link.

Reports

The record carries the recordId that the report route takes. See Verification reports.

Errors

CodeStatusCauseWhat to do
unknown_marker404The id is not one this account was given.Use an id from your own map responses, with the key of the same account.
marker_expired410The marker id is older than 24 hours.Request the view again for a new id, or use the recordRef.
record_no_longer_listed410The registry no longer lists the person. Not billed.Remove the pin and tell the user the record is no longer listed.

Product overview