Documentation de l'API
URL de base : https://developer.yakoua.fr/v1 · Réponses JSON (UTF-8) · HTTPS obligatoire.
curl "https://developer.yakoua.fr/v1/nearby?lat=48.5734&lng=7.7521&radius_km=5&limit=5" \
-H "Authorization: Bearer yk_live_VOTRE_CLE"Authentification
Envoyez votre clé dans l'en-tête Authorization: Bearer yk_live_… (ou X-API-Key). La clé n'est jamais acceptée dans l'URL : elle finirait dans les journaux des serveurs et des navigateurs.
Quotas et limites
Le quota mensuel et les limites de débit s'appliquent au compte, pas à la clé : vous pouvez créer autant de clés que nécessaire, elles partagent la même enveloppe.
| Offre | Quota mensuel | Limite instantanée | Requêtes / seconde | Prix |
|---|---|---|---|---|
| Découverte | 1 000 | 50 / minute | 1 | Gratuit |
| Starter | 10 000 | 300 / minute | 5 | 9 € / mois |
| Pro | 50 000 | 1 200 / minute | 20 | 29 € / mois |
| Business | 300 000 | 6 000 / minute | 100 | 99 € / mois |
- Seules les réponses
200sur un endpoint décompté consomment le quota. Erreurs,304(ETag) et endpoints système (/v1/ping,/v1/account) sont gratuits. - 80 % du quota : e-mail d'alerte + en-tête
X-Quota-Warning. - 100 % : si vous avez des requêtes supplémentaires (5 € les 5 000), elles prennent le relais sans interruption. Sinon, un compte payant passe en limitation temporaire (10 requêtes/minute, jusqu'à +20 % du quota) au lieu d'être coupé ; l'offre Découverte reçoit un
429. - En-têtes de réponse :
X-RateLimit-Limit/Remaining/Reset,X-Quota-Limit/Used/Remaining/Reset/State(ok,credits,throttled),X-Credits-Remaining,Retry-After.
Codes de réponse
| 200 | Requête réussie. |
| 304 | Contenu inchangé (envoyez If-None-Match avec l'ETag reçu) : non décompté. |
| 400 | Paramètre invalide ou manquant (error.code = invalid_parameter / missing_parameter). |
| 401 | Clé absente (missing_api_key) ou invalide (invalid_api_key). |
| 403 | Clé révoquée / expirée, IP ou origine non autorisée, compte suspendu, ou endpoint non inclus dans votre offre (plan_forbidden, avec required_plan). |
| 404 | Endpoint ou élément introuvable. |
| 429 | Limite de débit (rate_limited) ou quota (quota_exceeded) dépassé. Respectez Retry-After. |
| 500 | Erreur côté Yakoua. Indiquez le request_id au support. |
{ "error": { "code": "plan_forbidden", "message": "Cet endpoint n'est pas inclus dans votre offre Starter. Offre minimale : Pro.",
"current_plan": "starter", "required_plan": "pro" }, "request_id": "req_9f2c…" }
Paramètres de recherche
Communs à /v1/nearby, /v1/search, /v1/events, /v1/places, /v1/activities, /v1/discover, /v1/trending… Tous sont optionnels et combinables ; les paramètres inconnus sont ignorés et listés dans meta.ignored_params.
Position
lat, lng | nombre | Coordonnées du centre (WGS84). Les deux vont ensemble. |
radius_km | nombre | Rayon de recherche, 0,1 à 500 (défaut 10). |
bbox | minLng,minLat,maxLng,maxLat | Zone rectangulaire (alternative au rayon). |
city | liste | Limiter à une ou plusieurs villes (ex. Strasbourg,Colmar). |
Quoi
types | liste | events, places, activities (défaut : les trois). Ex. types=events pour uniquement des événements. |
mix | texte | Parts relatives par type dans la page : events:50,places:30,activities:20. Complète avec les meilleurs résultats si un type manque. |
limit_events, limit_places, limit_activities | entier | Nombre exact par type (alternative à mix). |
q | texte | Recherche plein texte (titre, description, ville, mots-clés, catégories). |
category | liste | Slug, nom ou catégorie historique (voir /v1/categories). |
subcategory, exclude_category | liste | Sous-catégories à garder ; catégories à exclure. |
tag, ambiance, audience | liste | Mots-clés, ambiances (action, entre-amis…) et publics (famille, amis, adultes…). |
Quand
when | texte | now, today, tomorrow, weekend, week, month. |
date_from, date_to | ISO 8601 | Plage précise (ex. 2026-12-24). Les événements qui chevauchent la plage sont inclus. Sans date, seuls les événements à venir ou en cours sont renvoyés. |
include_past | booléen | Inclure les événements passés. |
Budget et profil
free | booléen | true : gratuit uniquement ; false : payant. |
price_min, price_max | nombre | Prix par personne en euros. include_unknown_price=true garde les prix inconnus. |
age | nombre | Âge du participant : écarte ce qui est inadapté. |
kid_friendly, pmr | booléen | Adapté aux enfants ; accessible aux personnes à mobilité réduite. |
pet_friendly, parking, wifi, food_on_site, reservation_required | booléen | Équipements (événements). |
Cadre
environment | texte | indoor, outdoor ou mixed (raccourcis : indoor=true, outdoor=true). |
rain_ok, hot_ok, cold_ok | booléen | Compatible pluie / forte chaleur / froid. |
duration_min, duration_max | minutes | Durée de l'activité. |
rating_min, verified, boosted | nombre / booléen | Note minimale, établissements vérifiés, mises en avant. |
Résultat
sort | texte | relevance (défaut avec position/texte), distance, date, popularity, trending, rating, price, name. order=asc|desc inverse l'ordre. |
limit, offset, page | entier | Pagination. limit : 1–50 (100 en Business), défaut 20. |
fields | liste | Ne garder que certains champs (ex. name,price,location). |
include | liste | description_full, enrichment, gallery. |
Format des éléments
{
"type": "event" | "place" | "activity",
"id": "…", "slug": "…", "name": "…",
"category": { "slug": "spectacles-evenements", "name": "Musique" }, "subcategory": null,
"description": "…", "address": "…", "city": "Strasbourg",
"location": { "lat": 48.576, "lng": 7.729 }, "distance_km": 1.4,
"price": { "amount": 0, "free": true, "label": "Accès libre", "range": null, "currency": "EUR" },
"rating": 4.6, "review_count": 12, "image_url": "https://…", "url": "https://yakoua.fr/evenement/…",
"ambiances": [], "audiences": [], "tags": [], "environment": "outdoor",
"weather": { "rain_ok": null, "hot_ok": null, "cold_ok": null },
"duration_minutes": 120, "age": { "min": null, "max": null }, "accessibility": { "pmr": false },
"starts_at": "2026-11-27T17:00:00+01:00", "ends_at": "…", // événements
"phone": "…", "website": "…", "opening_hours": "…", "verified": true, // lieux et activités
"relevance": 87.5, "popularity": 340
}
Conditions d'utilisation : renvoyez vers la fiche d'origine via le champ url et mentionnez « Données Yakoua ». Les contenus restent la propriété de leurs auteurs.
Système
Vérifie votre clé et la disponibilité de l'API (non décompté du quota).
Offre, limites, consommation du mois et requêtes supplémentaires restantes pour votre compte (non décompté).
Autour de moi
Autour d'une position : événements, lieux et activités à faire à proximité, entièrement personnalisable (types, catégories, dates, budget, ambiance, mix…).
Recherche avancée par corps JSON : mêmes filtres que /v1/nearby, plus des blocs nommés (« sections ») pour composer une page en un seul appel.
Équivalent GET de la recherche avancée (mix=events:50,places:30,activities:20…).
Journée clé en main autour d'une position : matin, déjeuner, après-midi, soirée (météo, budget, enfants, centres d'intérêt).
Événements
Liste des événements à venir (filtrable).
Détail d'un événement (par id ou slug).
Événements qui ont lieu aujourd'hui.
Événements de demain.
Événements du week-end à venir (ou en cours).
Prochains événements, du plus proche au plus lointain.
Événements gratuits.
Événements autour d'une position.
Événements similaires à un événement donné.
À faire autour d'un événement (avant/après) : lieux et activités à proximité.
Lieux
Liste des lieux (bars, restaurants, culture…).
Détail d'un lieu (par id ou slug).
Lieux autour d'une position.
Lieux les mieux notés.
Lieux similaires à un lieu donné.
À faire autour d'un lieu.
Activités
Liste des activités et loisirs.
Détail d'une activité (par id ou slug).
Activités autour d'une position.
Activités similaires à une activité donnée.
À faire autour d'une activité.
Référentiels
Catégories et sous-catégories avec le nombre d'éléments par type.
Villes couvertes, avec leur centre et le nombre d'éléments.
Une catégorie, ses sous-catégories et ses éléments les plus populaires.
Chiffres clés du catalogue (effectifs par type, villes, dernière mise à jour).
Recherche
Recherche plein texte unifiée (événements, lieux, activités) avec tous les filtres.
Facettes disponibles pour une recherche (catégories, villes, prix, environnement, jours) avec leurs effectifs : idéal pour construire vos filtres.
Ce qui fait le plus parler en ce moment (par zone ou globalement).
Recommandations personnalisées selon des centres d'intérêt (interests=musique,nature) et un profil (audience, âge, budget).
Cartographie
Résultats en GeoJSON (FeatureCollection) pour une carte : bbox ou lat/lng/radius_km.
Flux iCalendar (.ics) des événements filtrés, importable dans Google Agenda, Apple Calendrier, Outlook.
Intégration
Jusqu'à 10 requêtes en un seul appel (chaque sous-requête compte pour 1 dans votre quota).
Flux de synchronisation : éléments créés ou modifiés depuis une date (since=2026-11-01T00:00:00+01:00). Idéal pour répliquer le catalogue.
Exemples
Uniquement des événements gratuits ce week-end
GET /v1/nearby?lat=48.5734&lng=7.7521&radius_km=15&types=events&when=weekend&free=true&sort=date
Moitié événements, moitié lieux, pour une sortie en famille s'il pleut
GET /v1/discover?lat=48.5734&lng=7.7521&mix=events:50,places:50&kid_friendly=true&rain_ok=true&limit=12
Une page d'accueil en un seul appel (sections nommées)
POST /v1/discover
{ "lat": 48.5734, "lng": 7.7521, "radius_km": 10, "limit": 6,
"sections": {
"ce_soir": { "types": "events", "when": "today" },
"a_manger": { "types": "places", "category": "manger-boire", "sort": "rating" },
"en_famille":{ "types": "activities", "kid_friendly": true, "rain_ok": true }
} }