AirportFusion

API 快速上手

使用 AirportFusion REST API，将地址到地址的直飞航班搜索集成到您自己的产品中。本指南带您从零开始，直到完成第一个成功的请求。

1. 创建账号和 API 密钥

  1. 注册（或登录）并打开开发者控制台。
  2. 进入 API 密钥 → 创建密钥，为其命名（例如“staging”），并选择一个套餐 — 免费套餐无需填写付款信息。
  3. 立即复制密钥：它仅显示一次。我们只存储它的哈希值。

密钥形如 af_live_xxxxxxxx…。前 12 个字符（即前缀）会一直显示在您的控制台中，方便您区分不同的密钥。

2. 身份验证

每个请求都需携带密钥，可以使用 Bearer 令牌或 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. 您的第一次搜索

GET /api/v1/search 接受以下参数：

| 参数 | 必填 | 说明 | | --- | --- | --- | | origin | 是 | 地址、城市、地标或 lat,lon 坐标 | | destination | 是 | 与 origin 相同 | | originRadiusKm | 是 | 50、100、150、200、300、500、1000 之一 | | destRadiusKm | 是 | 选项相同 | | departureDate | 否 | YYYY-MM-DD 格式，不能是过去的日期 | | passengers | 否 | 1–9，默认为 1 | | locale | 否 | en、fr、es、zh — 影响 AI 建议的语言 |

4. 读取响应

所有端点都返回一致的响应结构：

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

错误使用相同的结构，但 ok: false：

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

5. 速率限制与配额

每个响应都包含速率限制请求头：

  • X-RateLimit-Limit、X-RateLimit-Remaining — 您的每分钟限额窗口；
  • 收到 429 时，Retry-After 会告诉您何时可以重试。

每月配额在每个日历月的 1 日（UTC）重置。可在控制台中实时跟踪用量。

6. 需要处理的错误码

| HTTP | 代码 | 含义 | | --- | --- | --- | | 401 | invalid_api_key | 密钥缺失、已撤销或格式错误 | | 422 | validation_error | 参数有误 — 详情见 error.details | | 429 | rate_limited | 达到每分钟限制 — 请遵循 Retry-After | | 429 | quota_exceeded | 每月配额已用尽 — 请升级或等待 | | 500 | internal_error | 我们的问题 — 可安全地退避重试 |

7. 良好使用规范

  • 在您这一侧将相同的搜索缓存最多 24 小时。
  • 请记住所有数值都是估算值 — 向您的用户如实展示。
  • 使用 Free/Starter/Pro 套餐的集成必须显示“Powered by AirportFusion”署名（见 API 使用条款）。

有疑问？控制台中的开发者支持渠道是联系我们的最快方式。