Documentation de l'API

URL de base : https://developer.yakoua.fr/v1 · Réponses JSON (UTF-8) · HTTPS obligatoire.

Démarrage rapide. Connectez-vous à la console avec votre compte yakoua, créez une clé, puis :
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.

Appelez l'API depuis votre serveur. Une clé placée dans du JavaScript public est visible de tous. Si vous devez l'utiliser dans un navigateur, restreignez-la à vos origines autorisées (et éventuellement à vos IP) dans la console, et surveillez la consommation.

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.

OffreQuota mensuelLimite instantanéeRequêtes / secondePrix
Découverte1 00050 / minute1Gratuit
Starter10 000300 / minute59 € / mois
Pro50 0001 200 / minute2029 € / mois
Business300 0006 000 / minute10099 € / mois
  • Seules les réponses 200 sur 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

200Requête réussie.
304Contenu inchangé (envoyez If-None-Match avec l'ETag reçu) : non décompté.
400Paramètre invalide ou manquant (error.code = invalid_parameter / missing_parameter).
401Clé absente (missing_api_key) ou invalide (invalid_api_key).
403Clé 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).
404Endpoint ou élément introuvable.
429Limite de débit (rate_limited) ou quota (quota_exceeded) dépassé. Respectez Retry-After.
500Erreur 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, lngnombreCoordonnées du centre (WGS84). Les deux vont ensemble.
radius_kmnombreRayon de recherche, 0,1 à 500 (défaut 10).
bboxminLng,minLat,maxLng,maxLatZone rectangulaire (alternative au rayon).
citylisteLimiter à une ou plusieurs villes (ex. Strasbourg,Colmar).

Quoi

typeslisteevents, places, activities (défaut : les trois). Ex. types=events pour uniquement des événements.
mixtexteParts 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_activitiesentierNombre exact par type (alternative à mix).
qtexteRecherche plein texte (titre, description, ville, mots-clés, catégories).
categorylisteSlug, nom ou catégorie historique (voir /v1/categories).
subcategory, exclude_categorylisteSous-catégories à garder ; catégories à exclure.
tag, ambiance, audiencelisteMots-clés, ambiances (action, entre-amis…) et publics (famille, amis, adultes…).

Quand

whentextenow, today, tomorrow, weekend, week, month.
date_from, date_toISO 8601Plage 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_pastbooléenInclure les événements passés.

Budget et profil

freebooléentrue : gratuit uniquement ; false : payant.
price_min, price_maxnombrePrix par personne en euros. include_unknown_price=true garde les prix inconnus.
agenombreÂge du participant : écarte ce qui est inadapté.
kid_friendly, pmrbooléenAdapté aux enfants ; accessible aux personnes à mobilité réduite.
pet_friendly, parking, wifi, food_on_site, reservation_requiredbooléenÉquipements (événements).

Cadre

environmenttexteindoor, outdoor ou mixed (raccourcis : indoor=true, outdoor=true).
rain_ok, hot_ok, cold_okbooléenCompatible pluie / forte chaleur / froid.
duration_min, duration_maxminutesDurée de l'activité.
rating_min, verified, boostednombre / booléenNote minimale, établissements vérifiés, mises en avant.

Résultat

sorttexterelevance (défaut avec position/texte), distance, date, popularity, trending, rating, price, name. order=asc|desc inverse l'ordre.
limit, offset, pageentierPagination. limit : 1–50 (100 en Business), défaut 20.
fieldslisteNe garder que certains champs (ex. name,price,location).
includelistedescription_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

GET/v1/ping Découverte+gratuit

Vérifie votre clé et la disponibilité de l'API (non décompté du quota).

GET/v1/account Découverte+gratuit

Offre, limites, consommation du mois et requêtes supplémentaires restantes pour votre compte (non décompté).

Autour de moi

GET/v1/nearby Découverte+

Autour d'une position : événements, lieux et activités à faire à proximité, entièrement personnalisable (types, catégories, dates, budget, ambiance, mix…).

POST/v1/discover Pro+

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.

GET/v1/discover Pro+

Équivalent GET de la recherche avancée (mix=events:50,places:30,activities:20…).

GET/v1/plan Pro+

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

GET/v1/events Découverte+

Liste des événements à venir (filtrable).

GET/v1/events/{id} Découverte+

Détail d'un événement (par id ou slug).

GET/v1/events/today Starter+

Événements qui ont lieu aujourd'hui.

GET/v1/events/tomorrow Starter+

Événements de demain.

GET/v1/events/weekend Starter+

Événements du week-end à venir (ou en cours).

GET/v1/events/upcoming Starter+

Prochains événements, du plus proche au plus lointain.

GET/v1/events/free Starter+

Événements gratuits.

GET/v1/events/nearby Starter+

Événements autour d'une position.

GET/v1/events/{id}/similar Pro+

Événements similaires à un événement donné.

GET/v1/events/{id}/around Pro+

À faire autour d'un événement (avant/après) : lieux et activités à proximité.

Lieux

GET/v1/places Découverte+

Liste des lieux (bars, restaurants, culture…).

GET/v1/places/{id} Découverte+

Détail d'un lieu (par id ou slug).

GET/v1/places/nearby Starter+

Lieux autour d'une position.

GET/v1/places/top-rated Starter+

Lieux les mieux notés.

GET/v1/places/{id}/similar Pro+

Lieux similaires à un lieu donné.

GET/v1/places/{id}/around Pro+

À faire autour d'un lieu.

Activités

GET/v1/activities Découverte+

Liste des activités et loisirs.

GET/v1/activities/{id} Découverte+

Détail d'une activité (par id ou slug).

GET/v1/activities/nearby Starter+

Activités autour d'une position.

GET/v1/activities/{id}/similar Pro+

Activités similaires à une activité donnée.

GET/v1/activities/{id}/around Pro+

À faire autour d'une activité.

Référentiels

GET/v1/categories Découverte+

Catégories et sous-catégories avec le nombre d'éléments par type.

GET/v1/cities Découverte+

Villes couvertes, avec leur centre et le nombre d'éléments.

GET/v1/categories/{slug} Starter+

Une catégorie, ses sous-catégories et ses éléments les plus populaires.

GET/v1/stats Starter+

Chiffres clés du catalogue (effectifs par type, villes, dernière mise à jour).

Recherche

GET/v1/filters Starter+

Facettes disponibles pour une recherche (catégories, villes, prix, environnement, jours) avec leurs effectifs : idéal pour construire vos filtres.

GET/v1/recommendations Pro+

Recommandations personnalisées selon des centres d'intérêt (interests=musique,nature) et un profil (audience, âge, budget).

Cartographie

GET/v1/geojson Pro+

Résultats en GeoJSON (FeatureCollection) pour une carte : bbox ou lat/lng/radius_km.

GET/v1/events.ics Pro+

Flux iCalendar (.ics) des événements filtrés, importable dans Google Agenda, Apple Calendrier, Outlook.

Intégration

POST/v1/batch Business+

Jusqu'à 10 requêtes en un seul appel (chaque sous-requête compte pour 1 dans votre quota).

GET/v1/changes Business+

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 }
  } }