oedb-backend/doc/api_query_params.md

# OpenEventDatabase API Query Parameters

This document describes the query parameters that can be used to search for events in the OpenEventDatabase API.

## Base URL

The base URL for the API is:

```
http://api.openeventdatabase.org
```

## Endpoints

### GET /event

Returns events that match the specified criteria. By default, it returns the last events which are active "now".

## Query Parameters

The following query parameters can be used to filter events:

### `what`

Filters events by their category or type.

- **Format**: String
- **Example**: `what=weather.warning`
- **Description**: Returns events with a "what" value that starts with the provided string.

### `when`

Filters events by a specific timestamp.

- **Format**: ISO8601 date or keyword
- **Default**: "now"
- **Keywords**:
  - `now`: Current time
  - `today`: Today (00:00 to 23:59)
  - `yesterday`: Yesterday (00:00 to 23:59)
  - `tomorrow`: Tomorrow (00:00 to 23:59)
  - `lasthour`: Last hour
  - `nexthour`: Next hour
  - `lastXdays`, `lastXhours`, `lastXminutes`: X days/hours/minutes ago to now
  - `nextXdays`, `nextXhours`, `nextXminutes`: Now to X days/hours/minutes in the future
- **Example**: `when=2025-09-15T12:00:00Z` or `when=yesterday`
- **Description**: Returns events that are active at the specified time.

### `start` and `stop`

Filters events by a time range.

- **Format**: ISO8601 date or keyword (same as `when`)
- **Default**: "now" for both
- **Example**: `start=2025-09-10T00:00:00Z&stop=2025-09-15T23:59:59Z`
- **Description**: Returns events that overlap with the specified time range.

### `bbox`

Filters events by a geographic bounding box.

- **Format**: Four comma-separated values representing East, South, West, North coordinates
- **Example**: `bbox=-5.0,41.0,10.0,52.0`
- **Description**: Returns events located within the specified bounding box.

### `near`

Filters events by proximity to a location.

- **Format**: Two or three comma-separated values representing longitude, latitude, and optionally a maximum distance in meters
- **Default distance**: 1 meter if not specified
- **Example**: `near=2.3522,48.8566,50000` (events within 50km of Paris)
- **Description**: Returns events located within the specified distance from the given coordinates.

### `polyline`

Filters events by proximity to a polyline.

- **Format**: Encoded polyline string (as returned by routing engines like OSRM, GraphHopper, etc.)
- **Additional parameters**:
  - `buffer`: Distance in meters around the polyline (default: 1000)
  - `polyline_precision`: Precision of the encoded polyline (default: 5)
- **Example**: `polyline=_p~iF~ps|U_ulLnnqC_mqNvxq`A&buffer=5000`
- **Description**: Returns events located within the specified buffer distance around the encoded polyline.

### `geom`

Controls how geometry is returned in the response.

- **Format**: String or number
- **Values**:
  - `full`: Returns the full geometry
  - `only`: Returns only the geometry and event ID
  - Numeric value: Simplifies the geometry to the specified precision (e.g., `geom=0.01`)
- **Default**: Returns the centroid of the geometry
- **Example**: `geom=full` or `geom=0.01`
- **Description**: Controls the level of detail in the geometry portion of the response.

### `limit`

Limits the number of results returned.

- **Format**: Integer
- **Default**: 200
- **Example**: `limit=50`
- **Description**: Limits the number of events returned in the response.

### `type`

Filters events by their type.

- **Format**: String
- **Values**: "scheduled", "forecast", "unscheduled"
- **Example**: `type=scheduled`
- **Description**: Returns events of the specified type.

## Examples

### Weather alerts active on a specific date

```
GET /event?when=2025-09-15T12:00:00Z&what=weather.alert
```

Returns weather alerts that were active on September 15, 2025 at 12:00 UTC.

### Events near a location during a time range

```
GET /event?start=2025-09-15T12:00:00Z&stop=2025-09-15T14:00:00Z&near=2.3522,48.8566,10000
```

Returns events taking place within 10km of Paris on September 15, 2025 from 12:00 to 14:00 UTC.

### Traffic accidents near a location within the last 10 minutes

```
GET /event?what=traffic.accident&near=2.3522,48.8566,5000&when=last10minutes
```

Returns traffic accidents within 5km of Paris that occurred within the last 10 minutes.

### Events in a specific region with full geometry

```
GET /event?bbox=-5.0,41.0,10.0,52.0&geom=full
```

Returns events in France with their full geometry.

### Combining multiple parameters

```
GET /event?what=conference&start=2025-09-01T00:00:00Z&stop=2025-12-31T23:59:59Z&near=2.3522,48.8566,50000&limit=50
```

Returns up to 50 conference events within 50km of Paris between September 1 and December 31, 2025.

## Response Format

The API returns a GeoJSON FeatureCollection containing the events that match the query parameters. By default, the geometry portion is replaced by the event geometry centroid, unless you ask for full geometries using the `geom=full` parameter or `geom={snaptogrid}` to simplify the geometry.

Example response:

```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [2.3522, 48.8566]
      },
      "properties": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Conference event in Paris",
        "description": "Mock conference event for testing",
        "location": "Paris",
        "start": "2025-09-10T23:00:00",
        "stop": "2026-05-10T23:00:00",
        "createdate": "2025-09-15T23:00:00",
        "lastupdate": "2025-09-15T23:00:00",
        "lon": 2.3522,
        "lat": 48.8566
      }
    }
  ],
  "count": 1
}
```

## Limitations

- Only the first 200 events are returned by default. Use the `limit` parameter to adjust this.
- The API may return a 500 Internal Server Error if there are issues with the database connection or if the query is malformed.