Ignav

https://ignav.com/docs/
Admin
Ignav is a REST API that provides flight prices and booking links, enabling searches for one-way and...
Tokens:19,402
Snippets:170
Trust Score:5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Flight Search Response Example

Source: https://ignav.com/docs/quickstart

This is an example of the JSON response when searching for flights. It includes itinerary details such as price, carrier, duration, and a unique ignav_id.

```json
{
  "origin": "SFO",
  "destination": "JFK",
  "departure_date": "2026-05-11",
  "itineraries": [
    {
      "price": {
        "amount": 299,
        "currency": "USD"
      },
      "outbound": {
        "carrier": "American Airlines",
        "duration_minutes": 330,
        "segments": [
          {
            "marketing_carrier_code": "AA",
            "flight_number": "100",
            "operating_carrier_name": "American Airlines",
            "departure_airport": "SFO",
            "departure_time_local": "2026-05-11T08:00:00",
            "departure_timezone": "America/Los_Angeles",
            "departure_time_utc": "2026-05-11T15:00:00Z",
            "arrival_airport": "JFK",
            "arrival_time_local": "2026-05-11T16:30:00",
            "arrival_timezone": "America/New_York",
            "arrival_time_utc": "2026-05-11T20:30:00Z",
            "duration_minutes": 330,
            "aircraft": "Boeing 777"
          }
        ]
      },
      "cabin_class": "economy",
      "ignav_id": "5e4fcd2f1dc340649eb19f6ee2afb57a"
    }
  ]
}
```

--------------------------------

### API Response Example

Source: https://ignav.com/docs/booking-links

The API response contains itinerary details and a list of booking options. Each option includes legs and direct booking links with provider information and prices.

```json
{
  "itinerary": {
    "price": {
      "amount": 488,
      "currency": "USD"
    },
    "outbound": {
      "carrier": "American Airlines",
      "duration_minutes": 330,
      "segments": [
        {
          "marketing_carrier_code": "AA",
          "flight_number": "100",
          "operating_carrier_name": "American Airlines",
          "departure_airport": "SFO",
          "departure_time_local": "2026-05-11T08:00:00",
          "departure_timezone": "America/Los_Angeles",
          "departure_time_utc": "2026-05-11T15:00:00Z",
          "arrival_airport": "JFK",
          "arrival_time_local": "2026-05-11T16:30:00",
          "arrival_timezone": "America/New_York",
          "arrival_time_utc": "2026-05-11T20:30:00Z",
          "duration_minutes": 330,
          "aircraft": "Boeing 777"
        }
      ]
    },
    "cabin_class": "economy"
  },
  "booking_options": [
    {
      "legs": [
        "outbound"
      ],
      "links": [
        {
          "provider_name": "American Airlines",
          "provider_type": "airline",
          "fare_name": "Main Cabin",
          "price": {
            "amount": 488,
            "currency": "USD"
          },
          "url": "aa.com/booking/..."
        },
        {
          "provider_name": "Expedia",
          "provider_type": "third_party",
          "price": {
            "amount": 502,
            "currency": "USD"
          },
          "url": "expedia.com/flights/..."
        }
      ]
    }
  ]
}
```

--------------------------------

### Represent a connecting one-way flight itinerary

Source: https://ignav.com/docs/response-format

Example of an itinerary object containing two flight segments and pricing information.

```json
{
  "price": {
    "amount": 542,
    "currency": "USD"
  },
  "outbound": {
    "carrier": "United Airlines",
    "duration_minutes": 475,
    "segments": [
      {
        "marketing_carrier_code": "UA",
        "flight_number": "1234",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "SFO",
        "departure_time_local": "2026-05-11T06:00:00",
        "departure_timezone": "America/Los_Angeles",
        "departure_time_utc": "2026-05-11T13:00:00Z",
        "arrival_airport": "ORD",
        "arrival_time_local": "2026-05-11T12:15:00",
        "arrival_timezone": "America/Chicago",
        "arrival_time_utc": "2026-05-11T17:15:00Z",
        "duration_minutes": 255,
        "aircraft": "Boeing 737 MAX 9"
      },
      {
        "marketing_carrier_code": "UA",
        "flight_number": "5678",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "ORD",
        "departure_time_local": "2026-05-11T13:30:00",
        "departure_timezone": "America/Chicago",
        "departure_time_utc": "2026-05-11T18:30:00Z",
        "arrival_airport": "JFK",
        "arrival_time_local": "2026-05-11T16:55:00",
        "arrival_timezone": "America/New_York",
        "arrival_time_utc": "2026-05-11T20:55:00Z",
        "duration_minutes": 145,
        "aircraft": "Airbus A320"
      }
    ]
  },
  "cabin_class": "economy",
  "ignav_id": "a1b2c3d4e5f6789012345678abcdef01"
}
```

--------------------------------

### Search for Nonstop Weekend Round-Trip Flights

Source: https://ignav.com/docs/round-trip

This cURL example demonstrates how to find nonstop round-trip flights for a weekend getaway by combining `max_stops` with a short date range. Remember to use your API key.

```curl
curl -X POST "https://ignav.com/api/fares/round-trip" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"JFK","destination":"MIA","departure_date":"2026-05-01","return_date":"2026-05-03","adults":2,"max_stops":0}'
```

--------------------------------

### Get Round-Trip Booking Links (cURL)

Source: https://ignav.com/docs/booking-links

Include return flight details to request booking links for round-trip itineraries. Ensure all required inbound parameters are provided.

```curl
curl -X POST "https://ignav.com/api/fares/booking-links" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"LAX","destination":"NRT","departure_date":"2026-05-11","outbound_carrier_code":"NH","outbound_flight_number":"5","return_date":"2026-05-25","inbound_carrier_code":"NH","inbound_flight_number":"6","adults":2}'
```

--------------------------------

### Get Booking Links with Manual Flight Details (cURL)

Source: https://ignav.com/docs/booking-links

Provide manual flight details if an `ignav_id` is not available. This method is useful for specifying exact flight information.

```curl
curl -X POST "https://ignav.com/api/fares/booking-links" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"JFK","departure_date":"2026-05-11","outbound_carrier_code":"AA","outbound_flight_number":"100"}'
```

--------------------------------

### Get Booking Links (cURL)

Source: https://ignav.com/docs/quickstart

Use this cURL command to retrieve booking links for a specific flight itinerary. Pass the ignav_id obtained from a flight search in the JSON payload.

```curl
curl -X POST "https://ignav.com/api/fares/booking-links" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ignav_id":"5e4fcd2f1dc340649eb19f6ee2afb57a"}'
```

--------------------------------

### Round-Trip Flight Search Response

Source: https://ignav.com/docs/round-trip

This is an example JSON response for a round-trip flight search. It includes details for both the outbound and inbound legs of the journey.

```json
{
  "origin": "SFO",
  "destination": "LHR",
  "departure_date": "2026-05-11",
  "return_date": "2026-05-18",
  "itineraries": [
    {
      "price": {
        "amount": 899,
        "currency": "USD"
      },
      "outbound": {
        "carrier": "British Airways",
        "duration_minutes": 625,
        "segments": [
          {
            "marketing_carrier_code": "BA",
            "flight_number": "286",
            "operating_carrier_name": "British Airways",
            "departure_airport": "SFO",
            "departure_time_local": "2026-05-11T17:30:00",
            "departure_timezone": "America/Los_Angeles",
            "departure_time_utc": "2026-05-12T00:30:00Z",
            "arrival_airport": "LHR",
            "arrival_time_local": "2026-05-12T11:55:00",
            "arrival_timezone": "Europe/London",
            "arrival_time_utc": "2026-05-12T10:55:00Z",
            "duration_minutes": 625,
            "aircraft": "Airbus A380"
          }
        ]
      },
      "inbound": {
        "carrier": "British Airways",
        "duration_minutes": 660,
        "segments": [
          {
            "marketing_carrier_code": "BA",
            "flight_number": "287",
            "operating_carrier_name": "British Airways",
            "departure_airport": "LHR",
            "departure_time_local": "2026-05-18T10:00:00",
            "departure_timezone": "Europe/London",
            "departure_time_utc": "2026-05-18T09:00:00Z",
            "arrival_airport": "SFO",
            "arrival_time_local": "2026-05-18T13:00:00",
            "arrival_timezone": "America/Los_Angeles",
            "arrival_time_utc": "2026-05-18T20:00:00Z",
            "duration_minutes": 660,
            "aircraft": "Airbus A380"
          }
        ]
      },
      "cabin_class": "economy",
      "ignav_id": "a1b2c3d4e5f6789012345678abcdef01"
    }
  ]
}
```

--------------------------------

### Flight Price Tracker in Python

Source: https://ignav.com/docs/examples

Polls a flight route on a schedule, stores the lowest fare, and sends an alert when the price drops below a threshold. Requires the 'requests' and 'time' libraries.

```python
import requests, time

API_KEY = "YOUR_API_KEY"
ROUTE = {"origin": "SFO", "destination": "JFK", "departure_date": "2026-05-15"}
THRESHOLD = 250

def check_price():
    resp = requests.post(
        "https://ignav.com/api/fares/one-way",
        headers={"X-Api-Key": API_KEY},
        json=ROUTE,
    )
    resp.raise_for_status()
    itineraries = resp.json()["itineraries"]
    if not itineraries:
        return None
    return min(it["price"]["amount"] for it in itineraries)

while True:
    lowest = check_price()
    if lowest and lowest < THRESHOLD:
        print(f"Price drop! {lowest} USD on SFO-JFK")
        # send_alert(lowest)
    time.sleep(4 * 3600)  # poll every 4 hours
```

--------------------------------

### Combine Multiple Filters for Round-Trip

Source: https://ignav.com/docs/filtering

Demonstrates combining various filters for a round-trip search, including cabin class, price, time range, and specific airlines.

```cURL
curl -X POST "https://ignav.com/api/fares/round-trip" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"LHR","departure_date":"2026-05-11","return_date":"2026-05-18","adults":2,"cabin_class":"business","max_price":3000,"departure_time_range":{"earliest_hour":14,"latest_hour":22},"airlines_include":["BA","VS","AA"]}'
```

--------------------------------

### AI Travel Tool (MCP / Function Calling)

Source: https://ignav.com/docs/examples

Defines Ignav API endpoints as tool functions for an LLM agent, enabling it to look up airports, search fares, and fetch booking links. Requires the 'requests' library.

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE = "https://ignav.com/api"

def search_airports(query: str) -> list[dict]:
    """Look up airport IATA codes by name or city."""
    resp = requests.get(
        f"{BASE}/airports", params={"q": query},
        headers={"X-Api-Key": API_KEY},
    )
    return resp.json()

def search_fares(origin: str, destination: str, date: str) -> list[dict]:
    """Search one-way fares for a route and date."""
    resp = requests.post(
        f"{BASE}/fares/one-way",
        headers={"X-Api-Key": API_KEY},
        json={"origin": origin, "destination": destination, "departure_date": date},
    )
    data = resp.json()
    return [
        {"price": it["price"]["amount"], "carrier": it["outbound"]["carrier"],
         "ignav_id": it["ignav_id"]}
        for it in data["itineraries"][:5]
    ]

def get_booking_links(ignav_id: str) -> list[dict]:
    """Get grouped booking options for a specific itinerary."""
    resp = requests.post(
        f"{BASE}/fares/booking-links",
        headers={"X-Api-Key": API_KEY},
        json={"ignav_id": ignav_id},
    )
    return resp.json()["booking_options"]

# Register these as tools in your LLM framework of choice
```

--------------------------------

### Market Parameter Usage

Source: https://ignav.com/docs/markets

Details on how to use the market parameter to localize fare results.

```APIDOC
## Market Parameter

### Description
The `market` parameter controls the currency and locale of fare results. It determines the displayed currency, carrier name localization, and available booking providers.

### Parameters
#### Query Parameters
- **market** (string) - Optional - A 2-letter ISO 3166-1 alpha-2 country code. Defaults to 'US' (USD).
```

--------------------------------

### Booking Links API

Source: https://ignav.com/docs/solutions/ai-travel-tools

Generates a direct booking URL for a selected flight itinerary using its unique Ignav ID.

```APIDOC
## POST /api/fares/booking-links

### Description
Generates a direct booking URL for a specific flight itinerary identified by its `ignav_id`.

### Method
POST

### Endpoint
/api/fares/booking-links

#### Request Body
- **ignav_id** (string) - Required - The unique identifier for the flight itinerary.

### Request Example
```json
{
  "example": "{\"ignav_id\": \"5e4fcd2f1dc340649eb19f6ee2afb57a\"}"
}
```

### Response
#### Success Response (200)
- **booking_url** (string) - The direct URL to book the selected itinerary.

#### Response Example
```json
{
  "example": "{\"booking_url\": \"https://example.com/book/5e4fcd2f1dc340649eb19f6ee2afb57a\"}"
}
```
```

--------------------------------

### Search with market-specific pricing

Source: https://ignav.com/docs/one-way

Request specifying a market to receive pricing in a different currency.

```curl
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"LHR","destination":"DXB","departure_date":"2026-05-11","market":"GB"}'
```

--------------------------------

### Filter by Arrival Time Range

Source: https://ignav.com/docs/filtering

Filter flights based on arrival time using `arrival_earliest_hour` and `arrival_latest_hour`. Times are in the arrival airport's local time.

```cURL
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"LAX","destination":"LHR","departure_date":"2026-05-11","departure_time_range":{"arrival_earliest_hour":6,"arrival_latest_hour":12}}'
```

--------------------------------

### Search Airport Codes with cURL

Source: https://ignav.com/docs/airports

Use this cURL command to search for airport codes. Include your X-Api-Key in the request headers. The 'q' parameter specifies the search query, and 'limit' sets the maximum number of results.

```bash
curl "https://ignav.com/api/airports?q=san+fran&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"
```

--------------------------------

### Flight Search App in Next.js

Source: https://ignav.com/docs/examples

A server-side API route in Next.js that searches for flight fares and returns results to the frontend. It uses the 'next/server' library and requires an IGNAV_API_KEY environment variable.

```typescript
// app/api/search/route.ts
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const body = await req.json();
  const res = await fetch("https://ignav.com/api/fares/one-way", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.IGNAV_API_KEY!,
    },
    body: JSON.stringify({
      origin: body.origin,
      destination: body.destination,
      departure_date: body.date,
      adults: body.adults ?? 1,
    }),
  });
  if (!res.ok) {
    return NextResponse.json({ error: "Search failed" }, { status: res.status });
  }
  const data = await res.json();
  return NextResponse.json(data);
}
```

--------------------------------

### Price Object Details

Source: https://ignav.com/docs/response-format

Details about the price object within the fare search response.

```APIDOC
## Price Object

### Description
The `price` object always has an `amount` (number) and `currency` (3-letter ISO code). The currency is determined by the `market` you pass in the request, and the numeric amount is the displayed fare for that market.

### Fields
- **amount** (number) - The fare amount.
- **currency** (string) - The 3-letter ISO currency code.
```

--------------------------------

### Error Codes

Source: https://ignav.com/docs/errors

A comprehensive list of error codes, their associated HTTP status codes, and descriptions.

```APIDOC
## Error Codes

| Code | Status | Description |
|---|---|---|
| invalid_airport_query | 400 | Airport search query is shorter than 2 characters. |
| invalid_airport_code | 400 | Origin or destination is not a supported 3-letter IATA code. |
| duplicate_route_airports | 400 | Origin and destination are the same airport. |
| invalid_date_range | 400 | Return date is earlier than departure date. |
| missing_return_date | 400 | Round-trip request is missing the return_date field. |
| too_many_passengers | 400 | Total passenger count exceeds 9. |
| invalid_infants_on_lap | 400 | Lap infants exceed number of adults. |
| invalid_market | 400 | Market is not a valid 2-letter country code. |
| unsupported_market | 400 | Market is valid but not currently supported. |
| invalid_airline_code | 400 | An airline code is not a valid 2-character code. |
| conflicting_airline_filters | 400 | airlines_include and airlines_exclude share codes. |
| empty_airline_filter | 400 | airlines_include or airlines_exclude was provided but empty. |
| invalid_time_range | 400 | departure or arrival earliest_hour is greater than latest_hour. |
| invalid_fare_request | 400 | Fare request could not be translated into a valid upstream request. |
| invalid_booking_request | 400 | Booking request could not be translated into a valid upstream request. |
| missing_booking_fields | 400 | Manual booking request is missing required fields. |
| conflicting_booking_lookup_mode | 400 | Request mixes ignav_id with manual, passenger, or market fields. |
| missing_inbound_carrier_code | 400 | inbound_carrier_code is required when return_date is set. |
| missing_inbound_flight_number | 400 | inbound_flight_number is required when return_date is set. |
| unexpected_inbound_flight_number | 400 | return_date is required when inbound_flight_number is provided. |
| unexpected_inbound_carrier_code | 400 | return_date is required when inbound_carrier_code is provided. |
| ignav_id_not_found | 404 | The ignav_id was not found. |
| itinerary_not_found | 404 | Could not find the specified itinerary. |
| api_key_required | 401 | The X-Api-Key header is missing. |
| invalid_api_key | 401 | The X-Api-Key header is invalid. |
| email_not_verified | 403 | Email must be verified before calling API endpoints. |
| billing_required | 402 | Billing setup is required after free requests are exhausted. |
| billing_blocked | 402 | Billing is blocked for this account. |
| invalid_request_body | 400 | Request body is invalid (missing fields, wrong types, malformed JSON, or extra fields). |
| unable_to_complete_request | 424 | An upstream error occurred. Retry the request or try different parameters. |
```

--------------------------------

### Flight Leg and Segment Data Structure

Source: https://ignav.com/docs/one-way

This section details the structure of flight data, including leg and segment fields. This information is crucial for understanding flight itineraries.

```APIDOC
## Flight Data Structure

This API provides detailed flight information, broken down into legs and segments.

### Leg Fields

Represents a single leg of a journey, which may include layovers.

| Parameter | Type | Required | Description |
|---|---|---|---|
| carrier | string | No | Airline display name for this leg when available. |
| duration_minutes | integer | No | Elapsed leg travel time in minutes, including layovers when present. |
| segments | array | Yes | Array of flight segments for this leg (see below). |

### Segment Fields

Represents an individual flight segment within a leg.

| Parameter | Type | Required | Description |
|---|---|---|---|
| marketing_carrier_code | string | Yes | 2-letter airline code of the marketing carrier. |
| flight_number | string | Yes | Flight number. |
| operating_carrier_name | string | Yes | Name of the operating carrier (may differ from marketing carrier). |
| departure_airport | string | Yes | 3-letter IATA departure airport code. |
| departure_time_local | string | Yes | Local departure time in YYYY-MM-DDTHH:MM:SS format. |
| departure_timezone | string | Yes | IANA timezone name for the departure airport. |
| departure_time_utc | string | Yes | Departure timestamp converted to UTC (RFC 3339). |
| arrival_airport | string | Yes | 3-letter IATA arrival airport code. |
| arrival_time_local | string | Yes | Local arrival time in YYYY-MM-DDTHH:MM:SS format. |
| arrival_timezone | string | Yes | IANA timezone name for the arrival airport. |
| arrival_time_utc | string | Yes | Arrival timestamp converted to UTC (RFC 3339). |
| duration_minutes | integer | Yes | Duration of the segment in minutes. |
| aircraft | string | Yes | Aircraft type (e.g. "Boeing 777"). |

### Related Documentation

* [Round-Trip Fares](link-to-round-trip-fares)
* [Booking Links](link-to-booking-links)
* [Filtering](link-to-filtering)

```

--------------------------------

### POST /api/fares/booking-links

Source: https://ignav.com/docs/booking-links

Retrieve direct booking URLs for a specific flight itinerary. This endpoint can be used with either an `ignav_id` or manual flight details.

```APIDOC
## POST /api/fares/booking-links

### Description
Get direct booking URLs for a specific flight. There are two ways to request booking links: using an `ignav_id` from a previous fare search, or by manually specifying flight details.

### Method
POST

### Endpoint
/api/fares/booking-links

### Parameters
#### Request Body
**Option 1: Using ignav_id**
- **ignav_id** (string) - Required - The ignav_id from a previous fare search.

**Option 2: Manual flight details**
- **origin** (string) - Required - 3-letter IATA departure airport code.
- **destination** (string) - Required - 3-letter IATA arrival airport code.
- **departure_date** (string) - Required - Departure date in YYYY-MM-DD format.
- **outbound_carrier_code** (string) - Required - 2-character airline code for the outbound flight.
- **outbound_flight_number** (string) - Required - Flight number for the outbound flight.
- **return_date** (string) - Optional - Return date in YYYY-MM-DD format.
- **inbound_carrier_code** (string) - Optional - 2-character airline code for the return flight. Required when `return_date` is set.
- **inbound_flight_number** (string) - Optional - Flight number for the return flight. Required when `return_date` is set.
- **adults** (integer) - Optional - Number of adult passengers. Default: 1. Max total passengers: 9.
- **children** (integer) - Optional - Number of child passengers. Default: 0.
- **infants_in_seat** (integer) - Optional - Number of infants with their own seat. Default: 0.
- **infants_on_lap** (integer) - Optional - Number of lap infants. Cannot exceed adults. Default: 0.
- **market** (string) - Optional - 2-letter country code. Default: "US".

### Request Example
**Using ignav_id:**
```json
{
  "ignav_id": "5e4fcd2f1dc340649eb19f6ee2afb57a"
}
```

**Manual flight details (one-way):**
```json
{
  "origin": "SFO",
  "destination": "JFK",
  "departure_date": "2026-05-11",
  "outbound_carrier_code": "AA",
  "outbound_flight_number": "100"
}
```

**Manual flight details (round-trip):**
```json
{
  "origin": "LAX",
  "destination": "NRT",
  "departure_date": "2026-05-11",
  "outbound_carrier_code": "NH",
  "outbound_flight_number": "5",
  "return_date": "2026-05-25",
  "inbound_carrier_code": "NH",
  "inbound_flight_number": "6",
  "adults": 2
}
```

### Response
#### Success Response (200)
- **itinerary** (object) - Details of the flight itinerary.
  - **price** (object)
    - **amount** (number) - The price amount.
    - **currency** (string) - The currency code.
  - **outbound** (object) - Outbound flight details.
    - **carrier** (string) - The name of the carrier.
    - **duration_minutes** (integer) - The duration of the flight in minutes.
    - **segments** (array) - Array of flight segments.
      - **marketing_carrier_code** (string) - Marketing carrier code.
      - **flight_number** (string) - Flight number.
      - **operating_carrier_name** (string) - Operating carrier name.
      - **departure_airport** (string) - Departure airport code.
      - **departure_time_local** (string) - Local departure time.
      - **departure_timezone** (string) - Departure timezone.
      - **departure_time_utc** (string) - UTC departure time.
      - **arrival_airport** (string) - Arrival airport code.
      - **arrival_time_local** (string) - Local arrival time.
      - **arrival_timezone** (string) - Arrival timezone.
      - **arrival_time_utc** (string) - UTC arrival time.
      - **duration_minutes** (integer) - Duration of the segment in minutes.
      - **aircraft** (string) - Aircraft type.
  - **cabin_class** (string) - Cabin class of the flight.
- **booking_options** (array) - Array of available booking options.
  - **legs** (array) - Array of legs covered by this booking option.
  - **links** (array) - Array of booking links.
    - **provider_name** (string) - Name of the booking provider.
    - **provider_type** (string) - Type of the provider (e.g., "airline", "third_party").
    - **fare_name** (string) - Name of the fare (optional).
    - **price** (object) - Price for this specific booking link (optional).
      - **amount** (number) - The price amount.
      - **currency** (string) - The currency code.
    - **url** (string) - The direct booking URL.

#### Response Example
```json
{
  "itinerary": {
    "price": {
      "amount": 488,
      "currency": "USD"
    },
    "outbound": {
      "carrier": "American Airlines",
      "duration_minutes": 330,
      "segments": [
        {
          "marketing_carrier_code": "AA",
          "flight_number": "100",
          "operating_carrier_name": "American Airlines",
          "departure_airport": "SFO",
          "departure_time_local": "2026-05-11T08:00:00",
          "departure_timezone": "America/Los_Angeles",
          "departure_time_utc": "2026-05-11T15:00:00Z",
          "arrival_airport": "JFK",
          "arrival_time_local": "2026-05-11T16:30:00",
          "arrival_timezone": "America/New_York",
          "arrival_time_utc": "2026-05-11T20:30:00Z",
          "duration_minutes": 330,
          "aircraft": "Boeing 777"
        }
      ]
    },
    "cabin_class": "economy"
  },
  "booking_options": [
    {
      "legs": [
        "outbound"
      ],
      "links": [
        {
          "provider_name": "American Airlines",
          "provider_type": "airline",
          "fare_name": "Main Cabin",
          "price": {
            "amount": 488,
            "currency": "USD"
          },
          "url": "aa.com/booking/..."
        },
        {
          "provider_name": "Expedia",
          "provider_type": "third_party",
          "price": {
            "amount": 502,
            "currency": "USD"
          },
          "url": "expedia.com/flights/..."
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Legs and Segments

Source: https://ignav.com/docs/response-format

Information regarding the 'legs' and 'segments' within an itinerary.

```APIDOC
## Legs

### Description
Every itinerary includes an `outbound` leg. Round-trip itineraries may also include an `inbound` leg. Each leg contains airline display `carrier`, elapsed `duration_minutes`, and `segments`. Carrier names are display strings and may be localized. If you need a stable airline code, use each segment's `marketing_carrier_code`.

Optional itinerary fields are omitted when unavailable.

| Parameter         | Type    | Required | Description                                       |
|-------------------|---------|----------|---------------------------------------------------|
| carrier           | string  | No       | Airline display name for this leg when available. |
| duration_minutes  | integer | No       | Elapsed leg travel time in minutes, including layovers when present. |
| segments          | array   | Yes      | Array of flight segments for this leg (see below).|

## Segments

### Description
Each leg's `segments` array contains one entry per flight segment. A nonstop itinerary leg has one segment; a connection has two or more. Each segment includes:

| Parameter             | Type   | Required | Description                                       |
|-----------------------|--------|----------|---------------------------------------------------|
| marketing_carrier_code| string | Yes      | 2-letter code of the airline selling the ticket.    |
| flight_number         | string | Yes      | Flight number (e.g. "1234").                      |
| operating_carrier_name| string | Yes      | Name of the airline operating the aircraft.       |
| departure_airport     | string | Yes      | 3-letter IATA code.                               |
| departure_time_local  | string | Yes      | Local departure time in YYYY-MM-DDTHH:MM:SS format.|
| departure_timezone    | string | Yes      | IANA timezone name for the departure airport.     |
| departure_time_utc    | string | Yes      | Departure timestamp converted to UTC.             |
| arrival_airport       | string | Yes      | 3-letter IATA code.                               |
| arrival_time_local    | string | Yes      | Local arrival time in YYYY-MM-DDTHH:MM:SS format. |
| arrival_timezone      | string | Yes      | IANA timezone name for the arrival airport.       |
| arrival_time_utc      | string | Yes      | Arrival timestamp converted to UTC.               |
| duration_minutes      | integer| Yes      | Flight duration in minutes.                       |
| aircraft              | string | Yes      | Aircraft type, e.g. "Boeing 737 MAX 9".         |

`departure_time_local` and `arrival_time_local` remain airport-local wall times. Each segment also includes the corresponding IANA timezone and a UTC timestamp so browser clients do not have to infer the conversion.

Do not derive elapsed travel time by subtracting the local wall-clock fields. Use segment `duration_minutes`, leg `duration_minutes`, or the UTC timestamps instead.
```

--------------------------------

### Fare Search Response Structure

Source: https://ignav.com/docs/response-format

This section outlines the structure of the fare search response, detailing the top-level fields and the nested itinerary object.

```APIDOC
## Fare Search Response

### Description
All fare search responses follow the same structure. This page walks through each part so you know exactly what to expect.

### Top-level fields
Every fare response includes the route and date you searched, plus an array of matching itineraries:

| Parameter        | Type   | Required | Description                                    |
|------------------|--------|----------|------------------------------------------------|
| origin           | string | Yes      | The resolved 3-letter IATA departure code.     |
| destination      | string | Yes      | The resolved 3-letter IATA arrival code.       |
| departure_date   | string | Yes      | Departure date in YYYY-MM-DD format.           |
| return_date      | string | No       | Return date for round-trip responses.          |
| itineraries      | array  | Yes      | List of matching itineraries (may be empty).   |

### Itinerary object
Each itinerary represents a complete travel option. Here's a connecting one-way flight with two segments:

#### Single itinerary Example
```json
{
  "price": {
    "amount": 542,
    "currency": "USD"
  },
  "outbound": {
    "carrier": "United Airlines",
    "duration_minutes": 475,
    "segments": [
      {
        "marketing_carrier_code": "UA",
        "flight_number": "1234",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "SFO",
        "departure_time_local": "2026-05-11T06:00:00",
        "departure_timezone": "America/Los_Angeles",
        "departure_time_utc": "2026-05-11T13:00:00Z",
        "arrival_airport": "ORD",
        "arrival_time_local": "2026-05-11T12:15:00",
        "arrival_timezone": "America/Chicago",
        "arrival_time_utc": "2026-05-11T17:15:00Z",
        "duration_minutes": 255,
        "aircraft": "Boeing 737 MAX 9"
      },
      {
        "marketing_carrier_code": "UA",
        "flight_number": "5678",
        "operating_carrier_name": "United Airlines",
        "departure_airport": "ORD",
        "departure_time_local": "2026-05-11T13:30:00",
        "departure_timezone": "America/Chicago",
        "departure_time_utc": "2026-05-11T18:30:00Z",
        "arrival_airport": "JFK",
        "arrival_time_local": "2026-05-11T16:55:00",
        "arrival_timezone": "America/New_York",
        "arrival_time_utc": "2026-05-11T20:55:00Z",
        "duration_minutes": 145,
        "aircraft": "Airbus A320"
      }
    ]
  },
  "cabin_class": "economy",
  "ignav_id": "a1b2c3d4e5f6789012345678abcdef01"
}
```
```

--------------------------------

### Filter by Departure Time Range

Source: https://ignav.com/docs/filtering

Restrict departures to a specific time window using `departure_time_range`. Hours are in the departure airport's local time.

```cURL
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"JFK","departure_date":"2026-05-11","departure_time_range":{"earliest_hour":6,"latest_hour":11}}'
```

--------------------------------

### Filter by Minimum Baggage Requirements

Source: https://ignav.com/docs/filtering

Ensure results include a minimum number of checked or carry-on bags using `min_checked_bags` or `min_carry_on_bags`.

```cURL
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"NRT","departure_date":"2026-05-11","min_checked_bags":1}'
```

--------------------------------

### Filter by Maximum Price

Source: https://ignav.com/docs/filtering

Limit results to fares below a certain price threshold using `max_price`. The currency is determined by the market.

```cURL
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"JFK","destination":"MIA","departure_date":"2026-05-11","max_stops":0,"max_price":200}'
```

--------------------------------

### Retrieve Error Response Format

Source: https://ignav.com/docs/errors

The standard JSON structure returned for all API errors.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_airport_code",
    "message": "origin must be a supported 3-letter IATA code.",
    "field": "origin"
  }
}
```

--------------------------------

### Search for Flights (cURL)

Source: https://ignav.com/docs/quickstart

Use this cURL command to search for one-way flights. Include your API key in the header and specify origin, destination, and departure date in the JSON payload.

```curl
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"JFK","departure_date":"2026-05-11"}'
```

--------------------------------

### Resolve Airports with Ignav API

Source: https://ignav.com/docs/solutions/flight-search-apps

Use the airport search endpoint to convert city names into IATA codes. Requires an API key.

```curl
curl "https://ignav.com/api/airports?q=london&limit=3" \
  -H "X-Api-Key: YOUR_API_KEY"
```

--------------------------------

### Baggage Information

Source: https://ignav.com/docs/response-format

Details about baggage allowances included in the fare.

```APIDOC
## Baggage

### Description
When available, the `bags` object shows how many `carry_on` and `checked` bags are included in the fare. Either field may be omitted when the information is unavailable.

### Fields
- **carry_on** (integer) - Number of carry-on bags included.
- **checked** (integer) - Number of checked bags included.
```

--------------------------------

### Search One-Way Fares with Ignav API

Source: https://ignav.com/docs/solutions/flight-search-apps

Initiate a one-way fare search by providing origin, destination, and departure date. Filters like max stops and cabin class can be applied. Requires an API key and JSON content type.

```curl
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"LHR","departure_date":"2026-05-11","max_stops":0}'
```

--------------------------------

### POST /api/fares/round-trip

Source: https://ignav.com/docs/filtering

Search for round-trip flight fares with optional filtering parameters.

```APIDOC
## POST /api/fares/round-trip

### Description
Search for round-trip flight fares with support for complex filtering and cabin class selection.

### Method
POST

### Endpoint
https://ignav.com/api/fares/round-trip

### Request Body
- **origin** (string) - Required - Origin airport code
- **destination** (string) - Required - Destination airport code
- **departure_date** (string) - Required - Date of departure
- **return_date** (string) - Required - Date of return
- **cabin_class** (string) - Optional - Cabin class (e.g., business)
- **max_price** (number) - Optional - Maximum price threshold
- **departure_time_range** (object) - Optional - Departure time window
- **airlines_include** (array) - Optional - List of airlines to include

### Request Example
{
  "origin": "SFO",
  "destination": "LHR",
  "departure_date": "2026-05-11",
  "return_date": "2026-05-18",
  "adults": 2,
  "cabin_class": "business",
  "max_price": 3000,
  "departure_time_range": {
    "earliest_hour": 14,
    "latest_hour": 22
  },
  "airlines_include": ["BA", "VS", "AA"]
}
```

--------------------------------

### Search flight fares with Fare Search

Source: https://ignav.com/docs/solutions/ai-travel-tools

Pass resolved airport codes to retrieve structured flight itineraries for AI reasoning.

```cURL
curl -X POST "https://ignav.com/api/fares/one-way" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"SFO","destination":"NRT","departure_date":"2026-05-11"}'
```

--------------------------------

### POST /api/fares/one-way

Source: https://ignav.com/docs/filtering

Search for one-way flight fares with optional filtering parameters.

```APIDOC
## POST /api/fares/one-way

### Description
Search for one-way flight fares. You can apply various filters to narrow down the results.

### Method
POST

### Endpoint
https://ignav.com/api/fares/one-way

### Request Body
- **origin** (string) - Required - Origin airport code
- **destination** (string) - Required - Destination airport code
- **departure_date** (string) - Required - Date of departure (YYYY-MM-DD)
- **departure_time_range** (object) - Optional - Window for departure/arrival hours (0-23)
- **airlines_include** (array) - Optional - List of 2-character airline codes to include
- **airlines_exclude** (array) - Optional - List of 2-character airline codes to exclude
- **min_checked_bags** (integer) - Optional - Minimum required checked bags
- **min_carry_on_bags** (integer) - Optional - Minimum required carry-on bags
- **max_price** (number) - Optional - Maximum price threshold
- **max_stops** (integer) - Optional - Maximum number of stops
- **allow_separate_tickets** (boolean) - Optional - Whether to allow self-transfer itineraries
- **adults** (integer) - Optional - Number of adults
- **infants_on_lap** (integer) - Optional - Number of infants on lap
- **infants_in_seat** (integer) - Optional - Number of infants in their own seat

### Request Example
{
  "origin": "SFO",
  "destination": "JFK",
  "departure_date": "2026-05-11",
  "departure_time_range": {
    "earliest_hour": 6,
    "latest_hour": 11
  }
}
```
Tokens:
Raw