---
title: "Search spots and places"
description: "Real-time search over the map, backed by Postgres:\n\n- **`spots`**: mapped danger spots whose title, area or description matches `q`. Matching\n  is fuzzy (pg_trgm), so typos like `kalerw` or `nansna` still match, and prefix and\n  substring hits rank first.\n- **`places`**: places in Uganda matching `q` (from OpenStreetMap Nominatim, cached in the\n  database for 30 days), each with the mapped spots within **2 km** (`nearby`). Places\n  near mapped spots are listed first. This is how a search for \"Mulago\" surfaces the\n  Kalerwe spot 1.2 km away.\n\nFor search-as-you-type, call with `places=0` on every keystroke (spots only, typically\nunder 20 ms) and without it after a short pause.\n\nRate limits: **120 searches per minute**, and **30 uncached place lookups per minute**.\nWhen only the place lookup is throttled, the response is `429` but still contains the\nmatching `spots`.\n"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.deathspot.org/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Deathspot UG API › Search

`GET /api/search`

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`.

## Query parameters

- `search.query.q` (string, required) — Search text, 2–100 characters. Shorter queries return empty results.
  - minLength 2; maxLength 100; example `"Mulago"`
- `search.query.places` (string, optional) — Send `0` to skip place lookup and return mapped spots only. Places also need `q` of 3+ characters.
  - one of `"0"`, `"1"`; default `"1"`

## Code samples

### cURL

```curl
curl --request GET \
  --url 'https://deathspot.org/api/search?q=Mulago'
```

### TypeScript

```typescript
const url = 'https://deathspot.org/api/search?q=Mulago';
const options = {method: 'GET'};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://deathspot.org/api/search?q=Mulago"

response = requests.get(url)

print(response.text)
```

## Responses

### 200

Matching spots and places.

#### Example

```json
{
  "spots": [],
  "places": [
    {
      "name": "Mulago",
      "detail": "Kawempe, Kampala, Central Region",
      "lat": 0.3408,
      "lng": 32.5794,
      "nearby": [
        {
          "id": 7,
          "title": "Kalerwe",
          "area": "Kawempe",
          "category": "boda_gang",
          "severity": 5,
          "status": "confirmed",
          "moderator_verified": false,
          "lat": 0.34918,
          "lng": 32.57195,
          "distance_m": 1240
        }
      ]
    }
  ]
}
```

- `search.response.200.spots` (array<unknown>, required) — Up to 8 matching mapped spots, best first.
  - `search.response.200.spots.id` (integer, required)
  - `search.response.200.spots.title` (string, required)
  - `search.response.200.spots.area` (string, required)
  - `search.response.200.spots.category` (string, required) — What happens at the spot: `murder` (killing), `mob_action`, `boda_gang`, `robbery` (robbery or snatching), `stabbing` (stabbing or hacking), `kidnapping`, `other`.
    - one of `"murder"`, `"mob_action"`, `"boda_gang"`, `"robbery"`, `"stabbing"`, `"kidnapping"`, `"other"`
  - `search.response.200.spots.severity` (integer, required)
    - min 1; max 5
  - `search.response.200.spots.status` (string, required) — 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.
    - one of `"unverified"`, `"confirmed"`, `"disputed"`
  - `search.response.200.spots.moderator_verified` (boolean, required)
  - `search.response.200.spots.lat` (number, required)
    - format `double`
  - `search.response.200.spots.lng` (number, required)
    - format `double`
  - `search.response.200.spots.score` (number, required) — Relevance. Higher is better; only matches above 0.5 are returned.
    - example `1.8`
- `search.response.200.places` (array<object>, required) — Matching places, those near mapped spots first.
  - `search.response.200.places.name` (string, required)
    - example `"Mulago"`
  - `search.response.200.places.detail` (string, required) — Up to three levels of administrative context.
    - example `"Kawempe, Kampala, Central Region"`
  - `search.response.200.places.lat` (number, required)
    - format `double`
  - `search.response.200.places.lng` (number, required)
    - format `double`
  - `search.response.200.places.nearby` (array<unknown>, required) — Up to 5 mapped spots within 2 km, nearest first.
    - `search.response.200.places.nearby.id` (integer, required)
    - `search.response.200.places.nearby.title` (string, required)
    - `search.response.200.places.nearby.area` (string, required)
    - `search.response.200.places.nearby.category` (string, required) — What happens at the spot: `murder` (killing), `mob_action`, `boda_gang`, `robbery` (robbery or snatching), `stabbing` (stabbing or hacking), `kidnapping`, `other`.
      - one of `"murder"`, `"mob_action"`, `"boda_gang"`, `"robbery"`, `"stabbing"`, `"kidnapping"`, `"other"`
    - `search.response.200.places.nearby.severity` (integer, required)
      - min 1; max 5
    - `search.response.200.places.nearby.status` (string, required) — 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.
      - one of `"unverified"`, `"confirmed"`, `"disputed"`
    - `search.response.200.places.nearby.moderator_verified` (boolean, required)
    - `search.response.200.places.nearby.lat` (number, required)
      - format `double`
    - `search.response.200.places.nearby.lng` (number, required)
      - format `double`
    - `search.response.200.places.nearby.distance_m` (number, required) — Distance from the place in metres (at most 2000).
      - example `1240`
- `search.response.200.error` (string, optional) — 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.

#### Example

```json
{
  "spots": [
    {
      "id": 7,
      "title": "Kalerwe",
      "area": "Kawempe",
      "category": "boda_gang",
      "severity": 5,
      "status": "confirmed",
      "moderator_verified": false,
      "lat": 0.34918,
      "lng": 32.57195,
      "score": 1.8
    }
  ],
  "places": [],
  "error": "Too many place searches. Wait a minute and try again."
}
```

- `search.response.429.spots` (array<unknown>, required) — Up to 8 matching mapped spots, best first.
  - `search.response.429.spots.id` (integer, required)
  - `search.response.429.spots.title` (string, required)
  - `search.response.429.spots.area` (string, required)
  - `search.response.429.spots.category` (string, required) — What happens at the spot: `murder` (killing), `mob_action`, `boda_gang`, `robbery` (robbery or snatching), `stabbing` (stabbing or hacking), `kidnapping`, `other`.
    - one of `"murder"`, `"mob_action"`, `"boda_gang"`, `"robbery"`, `"stabbing"`, `"kidnapping"`, `"other"`
  - `search.response.429.spots.severity` (integer, required)
    - min 1; max 5
  - `search.response.429.spots.status` (string, required) — 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.
    - one of `"unverified"`, `"confirmed"`, `"disputed"`
  - `search.response.429.spots.moderator_verified` (boolean, required)
  - `search.response.429.spots.lat` (number, required)
    - format `double`
  - `search.response.429.spots.lng` (number, required)
    - format `double`
  - `search.response.429.spots.score` (number, required) — Relevance. Higher is better; only matches above 0.5 are returned.
    - example `1.8`
- `search.response.429.places` (array<object>, required) — Matching places, those near mapped spots first.
  - `search.response.429.places.name` (string, required)
    - example `"Mulago"`
  - `search.response.429.places.detail` (string, required) — Up to three levels of administrative context.
    - example `"Kawempe, Kampala, Central Region"`
  - `search.response.429.places.lat` (number, required)
    - format `double`
  - `search.response.429.places.lng` (number, required)
    - format `double`
  - `search.response.429.places.nearby` (array<unknown>, required) — Up to 5 mapped spots within 2 km, nearest first.
    - `search.response.429.places.nearby.id` (integer, required)
    - `search.response.429.places.nearby.title` (string, required)
    - `search.response.429.places.nearby.area` (string, required)
    - `search.response.429.places.nearby.category` (string, required) — What happens at the spot: `murder` (killing), `mob_action`, `boda_gang`, `robbery` (robbery or snatching), `stabbing` (stabbing or hacking), `kidnapping`, `other`.
      - one of `"murder"`, `"mob_action"`, `"boda_gang"`, `"robbery"`, `"stabbing"`, `"kidnapping"`, `"other"`
    - `search.response.429.places.nearby.severity` (integer, required)
      - min 1; max 5
    - `search.response.429.places.nearby.status` (string, required) — 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.
      - one of `"unverified"`, `"confirmed"`, `"disputed"`
    - `search.response.429.places.nearby.moderator_verified` (boolean, required)
    - `search.response.429.places.nearby.lat` (number, required)
      - format `double`
    - `search.response.429.places.nearby.lng` (number, required)
      - format `double`
    - `search.response.429.places.nearby.distance_m` (number, required) — Distance from the place in metres (at most 2000).
      - example `1240`
- `search.response.429.error` (string, required) — A human-readable message you can show to users.


Source: https://docs.deathspot.org/api/Search/search/index.md