> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Flight Calendar

> Search flights between a known origin and destination for flexible dates

Find priced itineraries between a known origin and destination using cached results, ideal when the user is flexible on dates. It answers questions like "cheapest week to fly Paris to Barcelona in June" or "best Friday to Sunday options from JFK to LAX next month". Each result includes an offer token you can pass into a live price check or directly into a trip.

<Accordion title="Tool description (what the LLM sees)" defaultOpen={false}>
  ```text theme={null}
  Search flights between a known origin and destination using cached pricing. Use this tool whenever the user specifies BOTH where they are flying FROM and where they are flying TO.

  WHEN TO USE THIS TOOL (CRITICAL):
  - The user provides both an origin AND a destination (city or airport)
  - Examples: "Paris to Barcelona", "JFK to CDG", "London to NYC for a weekend"
  - Supports loose / flexible dates: single dates, date arrays, date ranges, stay_days
  - ALSO the right tool for "cheapest flight", "best flight", "find me a flight", "cheapest date" phrasings: returns the cheapest cached itineraries.

  WHEN TO USE find_destination INSTEAD:
  - The user does NOT specify a destination: "Where should I go from Paris?", "Best deals from NYC"
  - The user wants inspiration: "Beach destinations from London", "Cheap flights from SF"

  WHEN TO USE flight_search INSTEAD:
  - The user has committed to EXACT dates: single departure date AND single return date on one specific route.
  - Example: "Paris → NYC, June 17 → June 26"
  - flight_search hits live pricing (each call has a cost) and is the step immediately before booking. Use only once route + both dates are locked.

  IMPORTANT:
    All dates in query parameters (departure_dates, departure_date_ranges, return_dates, return_date_ranges) MUST be in the future. Never use past dates.
    Please fill as much as possible search parameters based on user intent to get best results.
    Origin and destination must be IATA city code by default except if the user specifies IATA Airport code in the search.

  ROUTE SEARCH:
  - Use exact 3-letter IATA airport codes or IATA city code for both origin and destination
  - Date ranges OR stay duration for flexible trip planning
  - Natural trip duration (stay_days) instead of exact return dates
  - By default, please search roundtrip flights unless user specifies one-way. Use trip_type="oneway" ONLY when the user explicitly asks for a one-way trip

  USE CASES:
  ✓ "Find flights from JFK to CDG next month" - Specific route with date range
  ✓ "Fly from Los Angeles to Tokyo for a week in December" - Uses departure_date + stay_days
  ✓ "Paris to Barcelona for a weekend in April" - Specific route
  ✓ "Cheapest flight from ORD to LHR under $600" - Specific route with budget
  ✓ "Direct flight in business class from New York to London" - Specific route with preferences

  Flow: flight_calendar → flight_search (price-check) → trip → checkout
  ```
</Accordion>

## Parameters

| Name                    | Type                                                             | Required | Description                                                                          |
| ----------------------- | ---------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `origin`                | `string`                                                         | Yes      | Origin airport IATA code or city code (3 letters). Examples: "JFK", "PAR".           |
| `destination`           | `string`                                                         | Yes      | Destination airport IATA code or city code (3 letters). Examples: "CDG", "NRT".      |
| `trip_type`             | `enum ("oneway" \| "roundtrip")`                                 | Yes      | Trip type: "oneway" or "roundtrip".                                                  |
| `departure_dates`       | `array<string>`                                                  | No       | Specific departure dates (YYYY-MM-DD). Multiple dates searched with OR logic.        |
| `departure_date_ranges` | `array<object>`                                                  | No       | Departure date ranges for flexible search.                                           |
| `return_dates`          | `array<unknown>`                                                 | No       | Specific return dates (YYYY-MM-DD) for round-trip flights.                           |
| `return_date_ranges`    | `array<unknown>`                                                 | No       | Return date ranges for flexible round-trip search.                                   |
| `stay_days`             | `integer`                                                        | No       | Exact stay duration in days. Auto-calculates return date.                            |
| `stay_days_range`       | `object`                                                         | No       | Flexible stay duration range. Example: \{min: 5, max: 10}                            |
| `stay_days_range.min`   | `integer`                                                        | Yes      | Minimum stay duration in days                                                        |
| `stay_days_range.max`   | `integer`                                                        | Yes      | Maximum stay duration in days                                                        |
| `direct_only`           | `boolean`                                                        | No       | Only return nonstop flights.                                                         |
| `cabin_class`           | `enum ("economy" \| "premium_economy" \| "business" \| "first")` | No       | Cabin class filter.                                                                  |
| `max_total`             | `number`                                                         | No       | Maximum total price for the trip (canonical name). Preferred over max\_price.        |
| `max_price`             | `number`                                                         | No       | Deprecated alias for max\_total. Use max\_total instead.                             |
| `sort_by`               | `enum ("lowest" \| "recommendation")`                            | No       | Sort order. Default: "lowest" (cheapest first).                                      |
| `currency`              | `string`                                                         | No       | ISO 4217 currency code. Defaults to "USD".                                           |
| `locale`                | `string`                                                         | No       | BCP 47 locale. Defaults to "en-US".                                                  |
| `format`                | `enum ("text" \| "json")`                                        | No       | Response format. "text" returns plain text for LLMs. "json" returns structured JSON. |
| `limit`                 | `integer`                                                        | No       | Max results to return per page (1-100). Default 20.                                  |
| `offset`                | `integer`                                                        | No       | Number of results to skip, for pagination. Default 0.                                |

## Examples

**Cheapest days to fly JFK→CDG in June:**

```json theme={null}
{
  "name": "flight_calendar",
  "arguments": {
    "origin": "JFK",
    "destination": "CDG",
    "trip_type": "roundtrip",
    "departure_date_start": "2026-06-01",
    "departure_date_end": "2026-06-30",
    "stay_days": 7,
    "currency": "USD"
  }
}
```

**One-way, direct-only, business class:**

```json theme={null}
{
  "name": "flight_calendar",
  "arguments": {
    "origin": "CDG",
    "destination": "NRT",
    "trip_type": "oneway",
    "departure_date_start": "2026-09-01",
    "departure_date_end": "2026-09-30",
    "cabin_class": "business",
    "direct_only": true,
    "currency": "EUR"
  }
}
```

The response is a list of the cheapest flights found across the date range, not one entry per day. Each entry includes an `offer_token`; feed it to `flight_search` for live pricing before booking.