Démarrage rapide de l’API

Intégrez la recherche de vols directs d’adresse à adresse dans votre propre produit grâce à l’API REST AirportFusion. Ce guide vous accompagne de zéro jusqu’à votre première requête réussie.

1. Créez un compte et une clé API

Inscrivez-vous (ou connectez-vous) et ouvrez le tableau de bord développeur.
Allez dans Clés API → Créer une clé, donnez-lui un nom (p. ex. « staging ») et choisissez un plan — le plan Free ne nécessite aucune coordonnée bancaire.
Copiez la clé immédiatement : elle n’est affichée qu’une seule fois. Nous n’en stockons qu’un hachage.

Les clés ressemblent à af_live_xxxxxxxx…. Les 12 premiers caractères (le préfixe) restent visibles dans votre tableau de bord pour vous permettre de distinguer vos clés.

2. Authentifiez-vous

Envoyez la clé avec chaque requête, soit comme jeton Bearer, soit dans un en-tête X-Api-Key :

curl -H "Authorization: Bearer af_live_YOUR_KEY" \
  "https://your-airportfusion-host/api/v1/search?origin=Lyon&destination=Lisbon&originRadiusKm=100&destRadiusKm=150"

3. Votre première recherche

GET /api/v1/search accepte :

| Paramètre | Obligatoire | Description | | --- | --- | --- | | origin | oui | Adresse, ville, lieu emblématique ou lat,lon | | destination | oui | Identique à origin | | originRadiusKm | oui | L’une des valeurs 50, 100, 150, 200, 300, 500, 1000 | | destRadiusKm | oui | Mêmes options | | departureDate | non | YYYY-MM-DD, pas dans le passé | | passengers | non | 1–9, 1 par défaut | | locale | non | en, fr, es, zh — détermine la langue des conseils IA |

4. Lisez la réponse

Tous les points de terminaison renvoient une enveloppe cohérente :

{
  "ok": true,
  "data": {
    "searchId": "…",
    "origin": { "displayName": "Lyon, France", "lat": 45.76, "lon": 4.83 },
    "destination": { "displayName": "Lisboa, Portugal", "lat": 38.72, "lon": -9.14 },
    "originAirports": [ { "iata": "LYS", "distanceKm": 22.1 } ],
    "destinationAirports": [ { "iata": "LIS", "distanceKm": 6.9 } ],
    "routes": [
      {
        "id": "…",
        "flight": { "airlineCode": "TP", "estimatedDurationMinutes": 155, "estimatedPrice": 178.0 },
        "totals": { "estimatedCost": 214.5, "estimatedMinutes": 305, "currency": "EUR" },
        "score": 8.7
      }
    ],
    "meta": { "routeCount": 12, "durationMs": 840 }
  }
}

Les erreurs utilisent la même enveloppe avec ok: false :

{ "ok": false, "error": { "code": "validation_error", "message": "originRadiusKm must be one of …" } }

5. Limites de débit et quotas

Chaque réponse inclut des en-têtes de limitation de débit :

X-RateLimit-Limit, X-RateLimit-Remaining — votre fenêtre par minute ;
en cas de 429, Retry-After vous indique quand réessayer.

Les quotas mensuels se réinitialisent le 1er de chaque mois calendaire (UTC). Suivez votre consommation en temps réel dans le tableau de bord.

6. Codes d’erreur à gérer

| HTTP | Code | Signification | | --- | --- | --- | | 401 | invalid_api_key | Clé manquante, révoquée ou malformée | | 422 | validation_error | Paramètres invalides — détails dans error.details | | 429 | rate_limited | Limite par minute atteinte — respectez Retry-After | | 429 | quota_exceeded | Quota mensuel épuisé — passez à un plan supérieur ou patientez | | 500 | internal_error | Notre faute — réessayez sans risque avec un backoff |

7. Bonnes pratiques

Mettez en cache les recherches identiques de votre côté pendant 24 heures au maximum.
N’oubliez pas que chaque valeur est une estimation — présentez-la comme telle à vos utilisateurs.
Les intégrations Free/Starter/Pro doivent afficher une attribution « Powered by AirportFusion » (voir les Conditions d’utilisation de l’API).

Des questions ? Le canal d’assistance développeur de votre tableau de bord est le moyen le plus rapide de nous joindre.