oedb-backend/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_mqNvxqA&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:

{
  "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.