Search spots and places

Real-time search over the map, backed by Postgres:

spots: mapped danger spots whose title, area or description matches q. Matching is fuzzy (pg_trgm), so typos like kalerw or nansna still match, and prefix and substring hits rank first.
places: places in Uganda matching q (from OpenStreetMap Nominatim, cached in the database for 30 days), each with the mapped spots within 2 km (nearby). Places near mapped spots are listed first. This is how a search for "Mulago" surfaces the Kalerwe spot 1.2 km away.

For search-as-you-type, call with places=0 on every keystroke (spots only, typically under 20 ms) and without it after a short pause.

Rate limits: 120 searches per minute, and 30 uncached place lookups per minute. When only the place lookup is throttled, the response is 429 but still contains the matching spots.

GET

https://deathspot.org/api/search

View as Markdown

Query parameters

qstringrequired
Search text, 2–100 characters. Shorter queries return empty results.

maxLength: 100, minLength: 2
Example: "Mulago"
placesoptional0or1
Send 0 to skip place lookup and return mapped spots only. Places also need q of 3+ characters.

Default: "1"

Returns

200

Matching spots and places.

JSON

spotsarray ofunknownrequired
Up to 8 matching mapped spots, best first.
10 properties
- idintegerrequired
- titlestringrequired
- areastringrequired
- categorymurderormob_actionorboda_gangorrobberyorstabbingorkidnapping+1 morerequired
  What happens at the spot: murder (killing), mob_action, boda_gang, robbery (robbery or snatching), stabbing (stabbing or hacking), kidnapping, other.
- severityintegerrequired
  maximum: 5, minimum: 1
- statusunverifiedorconfirmedordisputedrequired
  The community's verdict from votes. confirmed needs at least 3 more confirmations than denials, and disputed means denials outnumber confirmations by more than 2.
- moderator_verifiedbooleanrequired
- latnumberrequired
  format: double
- lngnumberrequired
  format: double
- scorenumberrequired
  Relevance. Higher is better; only matches above 0.5 are returned.
  
  Example: 1.8
placesarray ofobjectrequired
Matching places, those near mapped spots first.
5 properties
- namestringrequired
  Example: "Mulago"
- detailstringrequired
  Up to three levels of administrative context.
  
  Example: "Kawempe, Kampala, Central Region"
- latnumberrequired
  format: double
- lngnumberrequired
  format: double
- nearbyarray ofunknownrequired
  Up to 5 mapped spots within 2 km, nearest first.
  
  10 properties
  idintegerrequired
  titlestringrequired
  areastringrequired
  categorymurderormob_actionorboda_gangorrobberyorstabbingorkidnapping+1 morerequired
  What happens at the spot: murder (killing), mob_action, boda_gang, robbery (robbery or snatching), stabbing (stabbing or hacking), kidnapping, other.
  
  severityintegerrequired
  maximum: 5, minimum: 1
  statusunverifiedorconfirmedordisputedrequired
  The community's verdict from votes. confirmed needs at least 3 more confirmations than denials, and disputed means denials outnumber confirmations by more than 2.
  
  moderator_verifiedbooleanrequired
  latnumberrequired
  format: double
  lngnumberrequired
  format: double
  distance_mnumberrequired
  Distance from the place in metres (at most 2000).
  
  Example: 1240
erroroptionalstring
Set when place search was skipped, e.g. the geocoder is unavailable.

429

Too many searches, or too many uncached place lookups. In the second case spots is still returned.

JSON

spotsarray ofunknownrequired
Up to 8 matching mapped spots, best first.
10 properties
- idintegerrequired
- titlestringrequired
- areastringrequired
- categorymurderormob_actionorboda_gangorrobberyorstabbingorkidnapping+1 morerequired
  What happens at the spot: murder (killing), mob_action, boda_gang, robbery (robbery or snatching), stabbing (stabbing or hacking), kidnapping, other.
- severityintegerrequired
  maximum: 5, minimum: 1
- statusunverifiedorconfirmedordisputedrequired
  The community's verdict from votes. confirmed needs at least 3 more confirmations than denials, and disputed means denials outnumber confirmations by more than 2.
- moderator_verifiedbooleanrequired
- latnumberrequired
  format: double
- lngnumberrequired
  format: double
- scorenumberrequired
  Relevance. Higher is better; only matches above 0.5 are returned.
  
  Example: 1.8
placesarray ofobjectrequired
Matching places, those near mapped spots first.
5 properties
- namestringrequired
  Example: "Mulago"
- detailstringrequired
  Up to three levels of administrative context.
  
  Example: "Kawempe, Kampala, Central Region"
- latnumberrequired
  format: double
- lngnumberrequired
  format: double
- nearbyarray ofunknownrequired
  Up to 5 mapped spots within 2 km, nearest first.
  
  10 properties
  idintegerrequired
  titlestringrequired
  areastringrequired
  categorymurderormob_actionorboda_gangorrobberyorstabbingorkidnapping+1 morerequired
  What happens at the spot: murder (killing), mob_action, boda_gang, robbery (robbery or snatching), stabbing (stabbing or hacking), kidnapping, other.
  
  severityintegerrequired
  maximum: 5, minimum: 1
  statusunverifiedorconfirmedordisputedrequired
  The community's verdict from votes. confirmed needs at least 3 more confirmations than denials, and disputed means denials outnumber confirmations by more than 2.
  
  moderator_verifiedbooleanrequired
  latnumberrequired
  format: double
  lngnumberrequired
  format: double
  distance_mnumberrequired
  Distance from the place in metres (at most 2000).
  
  Example: 1240
errorstringrequired
A human-readable message you can show to users.