Documentation
Cities Catalog
Access the full catalog of cities and locations known to the system. This endpoint returns the raw location records (without alert statistics) and is ideal for building dropdowns, lookup tables, and map layers.
GEThttps://sirenapi.orielhaim.com/data/cities
Returns a paginated list of cities/locations from the internal catalog.
Query Parameters
| Parameter | Type | Description | Default | Required |
|---|---|---|---|---|
| search | string | Search by city name (partial match, 1-100 chars) | - | no |
| zone | string | Filter by zone/region name (exact match) | - | no |
| limit | integer | Number of cities to return (1-500) | 100 | no |
| offset | integer | Number of results to skip for pagination | 0 | no |
| include | string | Comma-separated list of optional fields: translations, coords, countdown, polygons | - (none) | no |
The include Parameter
By default the response only contains id, name, andzone. Additional fields must be explicitly requested via theinclude parameter to minimize response size and database load.
| Value | Fields Added | Use Case |
|---|---|---|
| translations | translations.name, translations.zone | Multi-language UIs and region labels. |
| coords | lat, lng | Map rendering and spatial queries. |
| countdown | countdown | Showing shelter countdown times or safety timers in your UI. |
Example Requests
First 100 cities with minimal fields
bash
1GET https://sirenapi.orielhaim.com/data/cities
Response Structure
Always included
| Field | Type | Description |
|---|---|---|
| data[].id | number | Internal location identifier |
| data[].name | string | City name in Hebrew |
| data[].zone | string | null | Zone/region the city belongs to |
Optional - requires include
| Field | Type | Description | include |
|---|---|---|---|
| data[].translations | object | Translated name & zone (e.g. en, ru, ar) | translations |
| data[].lat | number | null | Latitude coordinate | coords |
| data[].lng | number | null | Longitude coordinate | coords |
| data[].polygon | geometry | null | Polygon geometry for the location | polygons |
| data[].countdown | number | null | Configured countdown time (seconds) for this location, if available | countdown |
Pagination
| Field | Type | Description |
|---|---|---|
| pagination.total | number | Total number of matching cities |
| pagination.limit | number | Requested limit |
| pagination.offset | number | Requested offset |
| pagination.hasMore | boolean | Whether more results are available |