-
Notifications
You must be signed in to change notification settings - Fork 7
Home
Welcome to the OpenEventDatabase API quick FAQ !
The goal of OpenEventDatabase is to share geo and time related data thru an open public API.
It tries to answer to what/where/when questions.
The basic data is an Event defined through a geojson paylod.
The geometry part contains the "where" information and the properties part contains the what and when details.
Real-time or "live" events can be shared like traffic informations, jams, accidents. Public transport related events can also be share like delays, cancellations. Safety alerts, weather warnings, are also useful to share. This first set of examples are unscheduled events.
A second type of event are scheduled ones, like public transport timetables, movie times, planned road works, holidays, etc.
The third type of events are the forecast ones, like weather forecast, traffic forecast.
Last type (so far) is observed events like weather temperature.
No private information or private events should be shared thru OpenEventDatabase. Copyrighted data cannot be shared due to all legal issues it could generate.
POST the event to http://api.openeventdatabase.org/event
The paylod must be a geojson Feature.
It contains the "where" information. It can be any kind of valid geometry (point, linestring, polygon, etc).
It contains the "what" and "when" details. The required fields are:
- type : scheduled / unscheduled / forecast / observed (see above)
- what : a hierarchical list of keywords describing the event
- when or start + stop : ISO8601 date/time field(s) to define the event points in time (when) or time range (start+stop). This fields must contain timezone information.
The API will return the event unique ID (uuid format) that has just been created.
GET http://api.openeventdatabase.org/event/{id}
The returned event is a valid geojson feature with the original fields and the following additionnal fields:
- id : the event uuid
- createdate : event creation timestamp (UTC based)
- lastupdate : event last update timestamp (UTC based)
Example:
{ "type":"Feature",
"properties":
{ "id": "c94dcdba-c8a8-4811-8dbd-e14a8c7a90a0",
"stop": "2016-04-21 16:00:00+00:00",
"type": "forecast",
"what": "weather.alert.wind",
"label": "Soyez vigilant: Vent violent",
"start": "2016-04-20 16:00:00+00:00",
"source": "http://vigilance.meteofrance.fr",
"createdate": "2016-05-03T16:12:55.87051",
"lastupdate": "2016-05-03T16:12:55.87051",
"alert_level": "alert",
"where_INSEE": "81"
},
"geometry":{"type":"Point","coordinates":[2.16571412880826,43.7857378154605]} },
...
GET http://api.openeventdatabase.org/event returns the last events which are active "now".
Parameters can be used to select events:
- what : will return event starting with the "what" parameter, example: what=weather.warning
- when : will return events overlapping with the timestamp provided (default is "now"), accepts ISO8601 formatted dates as well as keywords like now/today/yesterday/tomorrow/lasthour/nexthour/ (all combinations of last/next + number + months/days/hours/minutes)
- start and/or stop : will return events intersecting the timerange (defaults are "now", you can use relative keyword like LASTHOUR, NEXT2DAYS, etc)
- bbox : returns events in the corresponding geographic bounding box (E,S,W,N)
- near : returns events near the longitude,latitude provided. A maximum distance (in meters) can be given.
- polyline : returns events located with a buffer distance (in meters) around the encoded polyline (as returned by usual routing engines like OSRM, GraphHopper, etc)
Exemple: The result returned is a geojson FeatureCollection. 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: geom=0.01 will simplify geometry to 0.01°.
Only the first 200 events are returned.
Examples:
- weather alerts that were active on 2016-04-21 12:00: http://api.openeventdatabase.org/event?when=2016-04-21T12:00&what=weather.alert
- events taking place near longitude 2.1657 and latitude 43.7857 on 2016-04-21 from 12:00 to 14:00 http://api.openeventdatabase.org/event?start=2016-04-21T12:00&stop-2016-04-21T14:00&near=2.1657,43.7857
- traffic accidents near longitude 2.36 and latitude 48.85 (Paris center) within the last 10 minutes http://api.openeventdatabase.org/event?what=traffic.accident&near=2.36,48.85&when=last10minutes
As the search results are geojson Featurecollections, is it easy to display them on maps:
- Air pollution forecast around Paris
- Traffic problems around Paris
- Water level and flood alerts
- Euro2016 footbal matchs
- Historic aerial pictures
POST http://api.openeventdatabase.org/event/search allows to pass a geometry to search around.
The post payload must be a geojson feature, with the following parameters:
- what, when, start/stop can be used (see above)
- buffer to set a buffer around the given geometry (in meters, default is 1000 around Linestring and 0 for other types of geometry)
Example:
curl -X POST "http://api.openeventdatabase.org/event/search?when=today&buffer=500" -d @travel.json