Endpoints

Interroger les événements

Cette section documente l’endpoint public de consultation des événements publiés. Vous pouvez filtrer les résultats par période, texte libre et proximité géographique.

GET /api/v1/public/events Lecture publique authentifiée

Retourne la liste des événements publiés accessibles avec votre clé API consommateur. L’authentification se fait via l’en-tête X-API-Key.

Paramètre	Type	Description
`from`	date/datetime	Retourne les événements commençant à partir de cette date.
`to`	date/datetime	Retourne les événements commençant avant ou à cette date.
`q`	string	Recherche texte libre sur le titre, les descriptions et le lieu.
`lat`	float	Latitude du point de recherche pour le filtre de proximité.
`lng`	float	Longitude du point de recherche pour le filtre de proximité.
`radius_km`	float	Rayon de recherche en kilomètres autour du point `lat/lng`.

Authentification

curl -X GET "https://eventsdatas.cloud/api/v1/public/events" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

Exemple : filtre par période

curl -X GET "https://eventsdatas.cloud/api/v1/public/events?from=2026-04-01&to=2026-04-30" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

Exemple : recherche texte

curl -X GET "https://eventsdatas.cloud/api/v1/public/events?q=concert" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

Exemple : recherche de proximité

curl -X GET "https://eventsdatas.cloud/api/v1/public/events?lat=49.4298&lng=2.0837&radius_km=10" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

Exemple : combinaison de filtres

curl -X GET "https://eventsdatas.cloud/api/v1/public/events?from=2026-04-01&to=2026-04-30&q=expo&lat=49.4298&lng=2.0837&radius_km=15" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

Exemple de réponse

{
  "data": [
    {
      "id": "019d3f5b-c812-73da-9a7f-55cde7ac50ec",
      "title": "Exposition photo",
      "short_description": "Exposition des photographes locaux",
      "long_description": "Une sélection de clichés autour du patrimoine et du territoire.",
      "start_datetime": "2026-04-12T10:00:00+02:00",
      "end_datetime": "2026-04-12T18:00:00+02:00",
      "venue_name": "Galerie municipale",
      "address_line_1": "19 rue pierre jacoby",
      "postal_code": "60000",
      "city": "Beauvais",
      "country_code": "FR",
      "website_url": null,
      "booking_url": null,
      "status": "published",
      "latitude": 49.4297909,
      "longitude": 2.0836772,
      "image_url": null,
      "gallery_images": []
    }
  ]
}

Bonnes pratiques

Utilisez from et to pour limiter les volumes.
Le filtre de proximité nécessite que les événements aient été géocodés.
radius_km est exprimé en kilomètres, pas en mètres.
Si vous utilisez lat et lng, fournissez toujours aussi radius_km.

Utilisation avancée des filtres

Les filtres peuvent être combinés pour construire des recherches précises. L’API applique tous les filtres fournis sur la même requête.

Cas d’usage	Exemple
Période donnée	`?from=2026-04-01&to=2026-04-30`
Recherche texte	`?q=concert`
Proximité géographique	`?lat=49.4298&lng=2.0837&radius_km=10`
Recherche combinée	`?from=2026-04-01&to=2026-04-30&q=expo&lat=49.4298&lng=2.0837&radius_km=15`

Filtre de proximité (nearby)

Le filtre de proximité retourne les événements publiés situés dans un rayon donné autour d’un point géographique. Il repose sur les coordonnées géocodées des événements.

Paramètre	Obligatoire	Description
`lat`	Oui, si filtre nearby utilisé	Latitude du point central
`lng`	Oui, si filtre nearby utilisé	Longitude du point central
`radius_km`	Oui, si filtre nearby utilisé	Rayon de recherche en kilomètres

curl -X GET "https://eventsdatas.cloud/api/v1/public/events?lat=49.4298&lng=2.0837&radius_km=10" \
  -H "Accept: application/json" \
  -H "X-API-Key: votre_cle_api"

À noter

Le filtre nearby ne retourne que les événements disposant d’une géolocalisation valide.
radius_km est exprimé en kilomètres.
Les coordonnées doivent être envoyées en décimal, avec un point comme séparateur.

Recommandations d’intégration

Combinez from et to pour limiter le volume de données.
Utilisez q pour proposer une recherche simple côté interface utilisateur.
Utilisez le filtre nearby pour des usages carte, mobile ou découverte locale.
Prévoyez une gestion des réponses vides : aucun événement trouvé n’est pas une erreur API.
En cas de filtres géographiques, gardez des rayons raisonnables pour éviter des résultats trop larges.