Documentation — OpenEventDatabase

Concepts généraux

OpenEventDatabase répond à un manque : partager des informations spatio-temporelles de type « quoi / où / quand ». OpenStreetMap couvre le « quoi » et le « où », mais pas le « quand » ni l'historique d'évènements ponctuels ou récurrents.

Itinéraire temps réel

Un calcul d'itinéraire peut intégrer bouchons, travaux, météo ou incidents pour passer d'une appli passive à une appli temps réel.

Que faire ce week-end ?

Spectacles, activités, horaires de ciné — trouver un loisir proche de chez soi à partir d'évènements géolocalisés.

Mémoire territoriale

Conserver des évènements historiques, d'anciens tracés de routes, champs de bataille, découpages administratifs…

Les trois dimensions d'un évènement

Dans tous les cas d'usage, trois informations sont nécessaires :

Quoi Description sémantique : type (what), nature temporelle (scheduled, forecast, unscheduled), famille (culture, transport, météo…), importance.

Où Composante géographique : point lat/lon, géométrie GeoJSON, lien vers un référentiel (where:osm, where:wikidata).

Quand Temporalité ISO 8601 : instant, intervalle, récurrence ; mots-clés relatifs (today, next7days…).

Le projet propose une base spatio-temporelle ouverte pour échanger ces triplets, alimentée manuellement ou via des extracteurs automatisés depuis des sources ouvertes.

Format de données

L'API manipule des GeoJSON FeatureCollection. Chaque évènement est une Feature avec une géométrie et des propriétés métier.

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": { "type": "Point", "coordinates": [2.35, 48.86] },
    "properties": {
      "what": "culture.other",
      "type": "scheduled",
      "label": "Concert en plein air",
      "start": "2026-07-17T20:00:00Z",
      "stop": "2026-07-17T23:00:00Z"
    }
  }]
}

Schéma PostgreSQL

Base PostgreSQL avec PostGIS. Les géométries sont mutualisées dans geo ; les métadonnées évènement (label, description, source…) vivent dans events_tags (JSONB). Les suppressions sont archivées dans events_deleted. Les tables extractor_* alimentent le monitoring local des extracteurs.

Tables

Table	Rôle
`events`	Évènements actifs
`geo`	Géométries partagées (hash, geom PostGIS)
`events_deleted`	Archive des évènements supprimés
`extractor_registry`	Catalogue des extracteurs
`extractor_runs`	Historique d'exécution des extracteurs

events.events_geo référence geo.hash (FK). Index SP-GiST sur events_what / events_when, GIST sur geo.geom. Définition SQL : setup.sql et migrations/.

API REST

Base URL de production : https://api.openeventdatabase.org. L'éditeur Angular consomme la même API via le préfixe /api sur edit.oedb.cipherbliss.com.

Endpoints principaux

Méthode	Chemin	Description
GET	`/event`	Liste d'évènements (filtres query string)
POST	`/event`	Création d'un évènement (GeoJSON Feature)
GET/PUT/DELETE	`/event/{id}`	Lecture, mise à jour, suppression
GET	`/event/search`	Recherche spatiale avancée (géométrie POST)
GET	`/stats`	Statistiques agrégées
GET	`/rss`	Flux RSS des 200 derniers évènements
GET	`/db/dumps`	Liste des archives (instance locale)
POST	`/db/dumps/create`	Génère un dump SQL + GeoJSON

Paramètres de requête `GET /event`

Paramètre	Format	Description
`what`	string	Filtre par catégorie (préfixe), ex. `traffic.accident`
`when`	ISO8601 / mot-clé	`now`, `today`, `last7days`, `next30days`…
`start / stop`	ISO8601 / mot-clé	Plage temporelle (évènements qui chevauchent l'intervalle)
`bbox`	lon,lat,lon,lat	Boîte englobante (Est, Sud, Ouest, Nord)
`near`	lon,lat[,m]	Proximité d'un point ; distance max en mètres (défaut 1 m)
`polyline`	encodée	Évènements le long d'un itinéraire ; `buffer` en mètres
`type`	scheduled \| forecast \| unscheduled	Nature temporelle de l'évènement
`limit`	entier	Nombre max de résultats (défaut 200)
`offset`	entier	Pagination (si supportée par l'instance)
`geom`	full \| only \| nombre	Niveau de détail géométrique dans la réponse
`where:osm`	id OSM	Filtre par référentiel OpenStreetMap
`where:wikidata`	Q-id	Filtre par entité Wikidata

Exemples

# Alertes météo actives à une date
GET https://api.openeventdatabase.org/event?when=2026-07-15T12:00:00Z&what=weather.alert

# Accidents près de Paris (10 km, 10 dernières minutes)
GET https://api.openeventdatabase.org/event?what=traffic.accident&near=2.3522,48.8566,10000&when=last10minutes

# Conférences sur une plage temporelle
GET https://api.openeventdatabase.org/event?what=culture&start=2026-01-01&stop=2026-12-31&limit=50

# Évènements dans une bbox (France métropolitaine approx.)
GET https://api.openeventdatabase.org/event?bbox=-5.0,41.0,10.0,52.0&geom=full

Bac à sable interactif : Swagger Petstore (spec swagger.json sur la forge). Instance locale avec UI intégrée : /swagger. Détail des paramètres : doc/api_query_params.md.

Lancer l'API

Prérequis : PostgreSQL/PostGIS, Python 3, variables d'environnement (.env).

Docker (recommandé)

cp .env.example .env
docker-compose up -d
# API disponible sur http://localhost:8080

Installation locale

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
bash setup_db.sh
python3 backend.py
# ou : uwsgi --http :8080 --wsgi-file backend.py --callable app

Variables d'environnement

Variable	Rôle
`DB_NAME`, `DB_HOST`, `DB_USER`	Connexion PostgreSQL
`POSTGRES_PASSWORD`	Mot de passe base
`CLIENT_ID`, `CLIENT_SECRET`	OAuth (édition sécurisée)

Synchroniser des archives depuis l'API publique

python3 extractors/oedb_sync_extractor.py --mode sync \
  --since 2026-01-01 --until 2026-01-31 \
  --batch-size 1000 --no-dry-run --output-dir dumps

python3 scripts/generate_landing_html.py

Pages de l'éditeur

L'éditeur cartographique Angular est servi sur https://edit.oedb.cipherbliss.com. Il permet de visualiser, filtrer, créer et contrôler la qualité des évènements OEDB.

Route	Page	Description
/	Accueil / carte	Carte principale, filtres par type what, bascule carte/tableau, recherche.
/event/create	Créer un évènement	Formulaire de création avec géolocalisation et presets de catégories.
/agenda	Agenda	Vue calendrier (mois, semaine, jour) des évènements.
/unlocated-events	Événements non localisés	Liste des évènements sans coordonnées valides à corriger.
/quality-control	Contrôle qualité	Détection d'anomalies et validation des données.
/batch-edit	Modification en masse	Édition groupée de plusieurs évènements.
/events-docs	Events docs	Exploration des types what, presets et propriétés attendues.
/research	Research	Recherche avancée et exploration des jeux de données.
/nouvelles-categories	Nouvelles catégories	Suivi des types what émergents.
/stats	Statistiques	Comptages et tendances (proxy vers l'API /stats).
/demo	Hub démos	Index des démos thématiques alimentées par extracteurs.
/demo/ev-charging	Démo recharge VE	Sessions de recharge véhicule électrique.
/demo/wildlife-observations	Démo faune	Observations animales (cerfs, lucioles, chauves-souris…).
/demo/laws	Démo lois adoptées	Textes promulgués ou adoptés (CLAIR.vote).
/demo/science	Démo découvertes	Dates de découvertes scientifiques Wikidata.
/demo/space-launches	Démo lancements	Lancements spatiaux Launch Library 2.
/demo/bordeaux-associations	Démo assos Bordeaux	Agenda associatif bordelais.
/demo/renewable-construction	Démo éolien / solaire	Chantiers renouvelables (ODRÉ RNAé).
/extractors-monitor	Suivi extracteurs	Historique des runs d'extracteurs (JSON statique extractors-monitor.json).
/dumps	Archives dumps	Liste des snapshots GeoJSON/SQL (instance locale).

Ouvrir l'éditeur →

Archives de dumps

Snapshots GeoJSON et SQL générés par l'extracteur de synchronisation et par POST /db/dumps/create. Regroupés par année lorsque le nom de fichier contient une période (oedb_YYYYMM_…).

Année	Mois	Évènements	Taille	Téléchargements
2026	7	38 449	28.71 Mo	GeoJSON · ZIP
2025	12	107 142	82.59 Mo	GeoJSON · ZIP