up stuff
This commit is contained in:
Tykayn
tykayn
parent
656c3fd414
commit
1c17b57d8a
37 changed files with 2818 additions and 469 deletions
196
API_QUERY_PARAMS.md
Normal file
196
API_QUERY_PARAMS.md
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue