# api

## Pages

- [Deathspot UG API](https://docs.deathspot.org/api/index.md) — The Deathspot UG API powers the public map. Use it to read danger spots, report new ones,
confirm or deny existing spots, flag problems for moderators, and check a route for danger
spots.

- **No API key.** The public API is anonymous. Visitors are told apart by a salted,
  non-reversible hash of their IP address and user agent, which is used only for
  one-vote-per-spot and rate limits.
- **JSON in, JSON out.** Send `Content-Type: application/json` on every `POST`.
- **Uganda only.** Coordinates must fall inside Uganda's bounding box
  (latitude −1.6 to 4.3, longitude 29.5 to 35.1).
- **Rate limited.** Every endpoint returns `RateLimit-Limit`, `RateLimit-Remaining`,
  `RateLimit-Reset` and `RateLimit-Policy` headers, and `429` with `Retry-After` when you're
  over a limit. See the Rate limits guide.
- **Places, not people.** Reports describe locations. Phone numbers in free text are replaced
  with `[removed]`, and moderators delete anything that names or accuses a person.

Moderation (approving, hiding, editing and verifying spots) is not part of the public API.
Moderators use the `/admin` panel.

- [Report a problem with a spot](https://docs.deathspot.org/api/Community/flagSpot/index.md) — Sends a spot to the moderators' review queue with a reason.

Once a spot collects enough open flags (3 by default; admins can change this), it is
**hidden from the public map** until a moderator reviews it, and `result` is `hidden`.
Spots verified by moderators are never hidden automatically.

Each visitor can flag a spot once. Rate limit: **20 flags per hour** per visitor.

- [Confirm or deny a spot](https://docs.deathspot.org/api/Community/voteOnSpot/index.md) — Records the caller's answer to "Is this place still dangerous?".

- `1` means **still dangerous**. It also refreshes `last_confirmed_at`.
- `-1` means **not anymore**.

Each visitor has one vote per spot. Sending the opposite value changes the vote, and
sending the same value again returns `409`. After every vote the community `status` is
recalculated:

| Condition | `status` |
| --- | --- |
| `confirmations − denials ≥ 3` | `confirmed` |
| `denials > confirmations + 2` | `disputed` |
| otherwise | `unverified` |

Rate limit: **60 votes per hour** per visitor.

- [Get the caller's votes and site settings](https://docs.deathspot.org/api/Insights/getMe/index.md) — Returns the anonymous caller's existing votes, so a client can show which way they
voted, and whether new reports are currently held for review.

- [Get map statistics](https://docs.deathspot.org/api/Insights/getStats/index.md) — Aggregates across approved, non-disputed spots. Used by the public map's insights panel.
- [Check a route for danger spots](https://docs.deathspot.org/api/Routing/checkRoute/index.md) — Plans driving routes between two points (via OSRM, with alternatives) and lists every
reported spot within **150 m** of each route. Disputed spots are ignored.

Routes are sorted **safest first**: by `risk` (the sum of the severities of the spots
along the route), then by duration.

Rate limit: **20 route checks per minute** per visitor.

- [Search spots and places](https://docs.deathspot.org/api/Search/search/index.md) — 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`.

- [List danger spots](https://docs.deathspot.org/api/Spots/listSpots/index.md) — Returns every **approved** spot on the public map, ordered by severity (highest first),
then newest. Spots that are pending review or were rejected by moderators are never
returned.

The list is small enough to fetch in full; filter on the client for anything the query
parameters don't cover. The public map refreshes it every two minutes.

Rate limit: **120 requests per minute** per visitor (shared with `/api/stats` and `/api/me`).

- [Report a danger spot](https://docs.deathspot.org/api/Spots/reportSpot/index.md) — Adds a new danger spot. The reporter's own report counts as their first
"still dangerous" vote, so a new spot starts with `confirmations: 1` and
`status: unverified`.

What happens next depends on the site's moderation setting:

- **Instant publishing (default):** the spot is live immediately and `pending` is `false`.
- **Held for review:** the spot waits for a moderator and `pending` is `true`. It won't
  appear in `GET /api/spots` until it's approved.

Rate limits: **5 reports per hour** per visitor, and **30 per hour** per network (IP
address), since many phones share a carrier IP.

- [Health check](https://docs.deathspot.org/api/System/getHealth/index.md) — Returns `200` when the app can reach the database through Supabase. Docker uses this as the container health check.
- [Category](https://docs.deathspot.org/api/schemas/Category/index.md) — What happens at the spot:
`murder` (killing), `mob_action`, `boda_gang`, `robbery` (robbery or snatching),
`stabbing` (stabbing or hacking), `kidnapping`, `other`.

- [Error](https://docs.deathspot.org/api/schemas/Error/index.md)
- [FlagReason](https://docs.deathspot.org/api/schemas/FlagReason/index.md) — Why the spot needs a moderator:
`inaccurate` (wrong location or details), `names_person` (names or accuses a person),
`duplicate`, `abusive` (abusive or fake), `resolved` (no longer dangerous), `other`.

- [LatLng](https://docs.deathspot.org/api/schemas/LatLng/index.md)
- [NearbySpot](https://docs.deathspot.org/api/schemas/NearbySpot/index.md) — A mapped spot near a searched place.
- [NewSpot](https://docs.deathspot.org/api/schemas/NewSpot/index.md) — A new danger spot report.
- [Place](https://docs.deathspot.org/api/schemas/Place/index.md)
- [Route](https://docs.deathspot.org/api/schemas/Route/index.md)
- [RouteDanger](https://docs.deathspot.org/api/schemas/RouteDanger/index.md) — A danger spot near a route.
- [SearchResults](https://docs.deathspot.org/api/schemas/SearchResults/index.md)
- [Spot](https://docs.deathspot.org/api/schemas/Spot/index.md) — A reported danger spot on the public map.
- [SpotHit](https://docs.deathspot.org/api/schemas/SpotHit/index.md) — A mapped spot matching the search text.
- [SpotStatus](https://docs.deathspot.org/api/schemas/SpotStatus/index.md) — 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.

- [SpotSummary](https://docs.deathspot.org/api/schemas/SpotSummary/index.md) — The fields of a spot needed to show it in search results.
- [Stats](https://docs.deathspot.org/api/schemas/Stats/index.md)
- [TimeOfDay](https://docs.deathspot.org/api/schemas/TimeOfDay/index.md) — When the spot is dangerous.
- [ValidationError](https://docs.deathspot.org/api/schemas/ValidationError/index.md)
- [Community](https://docs.deathspot.org/api/tags/Community/index.md) — Confirm, deny and flag spots. This is how the community keeps the map accurate.
- [Insights](https://docs.deathspot.org/api/tags/Insights/index.md) — Aggregate statistics and the caller's own state.
- [Routing](https://docs.deathspot.org/api/tags/Routing/index.md) — Check a journey for reported danger spots.
- [Search](https://docs.deathspot.org/api/tags/Search/index.md) — Real-time search over mapped spots and places, with the danger spots near each place.
- [Spots](https://docs.deathspot.org/api/tags/Spots/index.md) — Read the map and report new danger spots.
- [System](https://docs.deathspot.org/api/tags/System/index.md) — Operational endpoints.