Skip to content
cquest edited this page Jul 28, 2016 · 14 revisions

Welcome to the OpenEventDatabase API quick FAQ !

The big picture

OpenEventDatabase logo

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.

Some events examples

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.

Where do we stop ?

No private information or private events should be shared thru OpenEventDatabase. Copyrighted data cannot be shared due to all legal issues it could generate.

Publish an event in database

POST the event to http://api.openeventdatabase.org/event

The paylod must be a geojson Feature.

Event geometry portion

It contains the "where" information. It can be any kind of valid geometry (point, linestring, polygon, etc).

Event properties portion

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 details about an event

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]} },
  ...

Search events using the API

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:

As the search results are geojson Featurecollections, is it easy to display them on maps:

Search events around a given geometry

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

Clone this wiki locally
You can’t perform that action at this time.