# Places



Any place on earth — search by name, look up by OSM id, reverse geocode from coordinates.



## Place Search

Any place on earth by name or address — the Google-Places replacement over open map data.

- Method: `GET`
- Path: `/v1/places/search`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `q` | string | required | A place name, address, or landmark. |
| `limit` | integer | optional | 1 to 50 results. |
| `max_age` | integer (seconds) | optional | Ask for data no older than this. Clamped to the product's own floor, so it can narrow the window but never force a refresh on every call. |

**Example request**

```bash
curl https://api.diraz.ae/v1/places/search \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "query": "coffee jakarta",
    "places": [
      {
        "osm_id": "W529345365",
        "name": "Otten Coffee Jakarta",
        "category": "amenity",
        "type": "cafe",
        "address": "Jakarta, Indonesia",
        "country_code": "ID",
        "lat": -6.2328214,
        "lon": 106.8120081
      }
    ]
  },
  "meta": { "request_id": "req_7Q2fK4mZ", "as_of": "2026-08-22T04:05:00.000Z", "age_seconds": 42, "next_update_at": "2026-08-23T04:05:00.000Z" }
}
```

## Reverse Geocode

Coordinates to the nearest address, worldwide — the other half of every maps integration.

- Method: `GET`
- Path: `/v1/places/reverse`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `lat` | number | required | Decimal degrees. |
| `lon` | number | required | Decimal degrees. |
| `limit` | integer | optional | How many nearby places, 1 to 10. |
| `max_age` | integer (seconds) | optional | Ask for data no older than this. Clamped to the product's own floor, so it can narrow the window but never force a refresh on every call. |

**Example request**

```bash
curl https://api.diraz.ae/v1/places/reverse \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "origin": { "lat": -6.2088, "lon": 106.8456 },
    "places": [
      {
        "osm_id": "W12345678",
        "name": "Sudirman Tower",
        "category": "building",
        "type": "office",
        "display_name": "Sudirman Tower, Jl. Jend. Sudirman, Jakarta, Indonesia",
        "lat": -6.2088,
        "lon": 106.8456
      }
    ]
  },
  "meta": { "request_id": "req_7Q2fK4mZ", "as_of": "2026-08-22T04:05:00.000Z", "age_seconds": 42, "next_update_at": "2026-08-23T04:05:00.000Z" }
}
```

## Place Detail

One place's complete OpenStreetMap record — address, phone, website, opening hours, wikidata — by OSM id.

- Method: `GET`
- Path: `/v1/places/detail`

**Parameters**

| Name | Type | | Description |
|---|---|---|---|
| `osm_id` | string | required | `N123`, `W456`, or `R789` — from a Place Search result. |
| `max_age` | integer (seconds) | optional | Ask for data no older than this. Clamped to the product's own floor, so it can narrow the window but never force a refresh on every call. |

**Example request**

```bash
curl https://api.diraz.ae/v1/places/detail \
  -H "Authorization: Bearer drz_live_…"
```

**Example response**

```json
{
  "data": {
    "osm_id": "W529345365",
    "name": "Otten Coffee Jakarta",
    "display_name": "Otten Coffee Jakarta, Jakarta, Indonesia",
    "category": "amenity",
    "type": "cafe",
    "lat": -6.2328214,
    "lon": 106.8120081,
    "address": { "city": "Jakarta", "country": "Indonesia", "country_code": "id" },
    "extratags": { "building": "yes" }
  },
  "meta": { "request_id": "req_7Q2fK4mZ", "as_of": "2026-08-22T04:05:00.000Z", "age_seconds": 42, "next_update_at": "2026-08-23T04:05:00.000Z" }
}
```