{
  "openapi": "3.1.0",
  "info": {
    "title": "Travel Intelligence subscriber API",
    "version": "1.0.0",
    "description": "Reference for the six documented pricing and availability operations. Use the production endpoint and key supplied with your subscription.",
    "contact": {
      "name": "Travel Intelligence LLC",
      "url": "https://www.bestawardintelligence.com/company/"
    }
  },
  "servers": [
    {
      "url": "https://api.bestawardintelligence.com",
      "description": "Illustrative base URL used in the subscriber documentation"
    }
  ],
  "externalDocs": {
    "url": "https://www.bestawardintelligence.com/api-reference/"
  },
  "paths": {
    "/flight_trigger/search_real_time": {
      "post": {
        "operationId": "search_real_time",
        "tags": [
          "Flight award pricing"
        ],
        "summary": "Start a flight search",
        "description": "Search one departure date. Use three-letter airport codes, licensed program codes and the number of travelers as a string.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "origin",
                  "destination",
                  "date",
                  "programs",
                  "cabins",
                  "pax",
                  "api_key"
                ],
                "properties": {
                  "origin": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "destination": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "date": {
                    "type": "string",
                    "format": "date"
                  },
                  "programs": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "cabins": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "pax": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "origin": "JFK",
                "destination": "LHR",
                "date": "2027-02-15",
                "programs": [
                  "AA"
                ],
                "cabins": [
                  "Business"
                ],
                "pax": "1",
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Save the returned task_id to retrieve priced itineraries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "task_id": "example-flight-search-01"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    },
    "/flight_retrieval/search_result": {
      "post": {
        "operationId": "search_result",
        "tags": [
          "Flight award pricing"
        ],
        "summary": "Read flight results",
        "description": "Pass the task_id from the search. Collect each result batch and continue polling while finish is false.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "task_id",
                  "api_key"
                ],
                "properties": {
                  "task_id": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "task_id": "example-flight-search-01",
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Each result can include a loyalty program, itinerary, cabin, points, cash fees and observed seat count.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "task_id": "example-flight-search-01",
                      "finish": true,
                      "result": [
                        {
                          "program_code": "AA",
                          "date": "2027-02-15",
                          "cabin_type": "Business",
                          "award_points": 57500,
                          "surcharge": 5.6,
                          "currency": "USD",
                          "seats": 1,
                          "fare": {
                            "products": [
                              {
                                "origin": "JFK",
                                "destination": "LHR",
                                "cabin_type": "Business"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    },
    "/panorama/panorama_calendar_data": {
      "post": {
        "operationId": "panorama_calendar_data",
        "tags": [
          "Route price calendars"
        ],
        "summary": "Read a route calendar",
        "description": "Pass the departure and arrival airport codes separated by a hyphen. The direction of travel matters.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "api_key"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "id": "SFO-JFK",
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rows group observed award prices by date and program. Nonstop prices are reported separately when available.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "data": [
                        {
                          "date": "2027-02-15",
                          "route": "SFO-JFK",
                          "program": "AA",
                          "points": {
                            "y": 12500,
                            "j": 42500,
                            "ls": 1794240000,
                            "ss": {
                              "y": 2,
                              "j": 1
                            }
                          },
                          "points_ns": {
                            "y": 15000,
                            "j": 42500,
                            "ls": 1794240000
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    },
    "/api/hotel_all": {
      "post": {
        "operationId": "hotel_all",
        "tags": [
          "Hotel room pricing"
        ],
        "summary": "List supported properties",
        "description": "Send your subscription key to retrieve the property catalog available to your account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "api_key"
                ],
                "properties": {
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Use the id field from a property record as hotel_id when requesting its calendar.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "data": [
                        {
                          "id": "hyatt_kauai",
                          "name": "Grand Hyatt Kauai Resort & Spa"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    },
    "/api/hotel_calendar": {
      "post": {
        "operationId": "hotel_calendar",
        "tags": [
          "Hotel room pricing"
        ],
        "summary": "Read nightly hotel rates",
        "description": "Pass the full property ID, including the brand prefix, from the hotel list.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "hotel_id",
                  "api_key"
                ],
                "properties": {
                  "hotel_id": {
                    "type": "string"
                  },
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "hotel_id": "hyatt_kauai",
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "In data[0], each check-in date maps to a list of room rates. Cash-only offers can omit the points rate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "hotel_info": {
                        "id": "hyatt_kauai",
                        "name": "Grand Hyatt Kauai Resort & Spa"
                      },
                      "data": [
                        {
                          "2027-02-15": [
                            {
                              "avail_date": "2027-02-15",
                              "cash_price": "675",
                              "points_rate": 30000,
                              "point_value": "2.25",
                              "room_type": "1 King Bed",
                              "rate_plan": "Standard Room"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    },
    "/api/seatmap": {
      "post": {
        "operationId": "seatmap",
        "tags": [
          "Seat maps"
        ],
        "summary": "Read a seat map",
        "description": "Supply the operating flight and airports, the departure date and a cabin code for one segment.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "flight",
                  "api_key"
                ],
                "properties": {
                  "flight": {
                    "type": "object",
                    "required": [
                      "id",
                      "airlineCode",
                      "flightNo",
                      "departureDate",
                      "departure",
                      "arrival",
                      "cabinClass"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "airlineCode": {
                        "type": "string"
                      },
                      "flightNo": {
                        "type": "string"
                      },
                      "departureDate": {
                        "type": "string",
                        "format": "date"
                      },
                      "departure": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$"
                      },
                      "arrival": {
                        "type": "string",
                        "pattern": "^[A-Z]{3}$"
                      },
                      "cabinClass": {
                        "type": "string"
                      }
                    }
                  },
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Subscription key supplied to your team."
                  }
                }
              },
              "example": {
                "flight": {
                  "id": "VS20",
                  "airlineCode": "VS",
                  "flightNo": "20",
                  "departureDate": "2027-02-15",
                  "departure": "SFO",
                  "arrival": "LHR",
                  "cabinClass": "E"
                },
                "api_key": "YOUR_API_KEY"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Match seat labels in the availability record to the layout for the flight.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "examples": {
                  "illustrative": {
                    "summary": "Illustrative response excerpt",
                    "value": {
                      "status": 200,
                      "data": [
                        {
                          "id": "VS20",
                          "seatDetails": {
                            "decks": [
                              {
                                "level": 1,
                                "rows": [
                                  {
                                    "number": 57,
                                    "classCode": "E",
                                    "seats": [
                                      {
                                        "letter": "A",
                                        "name": "Economy"
                                      }
                                    ]
                                  }
                                ]
                              }
                            ]
                          }
                        },
                        {
                          "id": "availabilityData",
                          "availableSeats": [
                            {
                              "label": "57A",
                              "price": 0,
                              "currency": "EUR"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Check the required request fields."
          },
          "401": {
            "description": "A valid subscription key is required."
          },
          "403": {
            "description": "Check subscription access for this dataset."
          }
        }
      }
    }
  }
}
