Price calendar
price_calendarUse price_calendar only for a traveler who is flexible within a period they named (for example "sometime in March", "any weekend in December", "this winter"), has told you how many nights they want to stay, and wants to know which days are cheapest.
It shows the cheapest fare for each departure day, across about two months starting with the month you give. With max_stops=0 it also shows which days have a nonstop flight, for a traveler who is flexible within a period they named and wants a nonstop.
Every price in the calendar is for one exact trip: a set number of nights away, one cabin, one number of travelers, and one set of stops, airlines and times. If any of these is guessed, every price in the calendar is for a trip the traveler will not take.
Before you call it, you need from the traveler: the month or period, and for a round trip the number of nights they want to stay. Also pass any preferences the traveler gave you: nonstop or not, airlines, times of day, cabin, and number of travelers. If the traveler has not told you the period, or for a round trip the number of nights, ask them in one question. Do not choose a month for the traveler. Do not choose a trip length for the traveler.
Do not call this tool when the traveler has given you dates. Search those dates with search_flights instead. Do not call this tool when the traveler has given no dates at all. Ask them when they want to go instead, and offer a bucket list alert with add_flight_bucket_list, which watches the route for them.
Call it once, or twice at most, per answer. Then show the traveler the two or three cheapest days. The answer tells you how to close: one question that offers flights for the day they pick, or a bucket list alert that watches the whole period.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cabin | No | Cabin class. | economy |
| month | No | The month the traveler named, as YYYY-MM. Leave it empty only when the traveler asked about the next few weeks. Do not choose a month for the traveler. | |
| origin | Yes | A 3-letter airport code (JFK), or a city code that searches every airport in the city (SlickTrip's 4-letter codes: NYCA New York, LOND London, ROME Rome, TYOA Tokyo). Up to 3 places joined with _ search them together (JFK_EWR). A place name works when one place clearly matches; otherwise the result is an unknown_place error listing suggestions. When the traveler names a city rather than an airport, send the city (its name or code), not one of its airports: one airport can miss the cheapest or the only flights. Unsure of the code: call find_places. | |
| airlines | No | Up to 3 carriers as IATA codes, or one alliance: star alliance, oneworld, skyteam. | |
| depart_to | No | YYYY-MM-DD, the last day the traveler could leave. | |
| max_stops | No | Most stops allowed: 0 nonstop, 1, or 2 (2 or more: any number). | |
| travelers | No | Travelers who need a seat (adults and children). Fares are quoted for all of them together; one booking holds up to 9 (a larger group gets a suggested split). A baby under 2 on a lap is not a seat and is not counted here. | |
| trip_type | No | Round trip or one way. | roundtrip |
| depart_from | No | YYYY-MM-DD, with depart_to: only departures in the traveler's own window ("any day before Christmas" is December 1 to 24; "mid-March through April" is March 15 to April 30). It can run to the end of the month after depart_from. | |
| destination | Yes | A 3-letter airport code (JFK), or a city code that searches every airport in the city (SlickTrip's 4-letter codes: NYCA New York, LOND London, ROME Rome, TYOA Tokyo). Up to 3 places joined with _ search them together (JFK_EWR). A place name works when one place clearly matches; otherwise the result is an unknown_place error listing suggestions. When the traveler names a city rather than an airport, send the city (its name or code), not one of its airports: one airport can miss the cheapest or the only flights. Unsure of the code: call find_places. | |
| lap_infants | No | Babies under 2 who will sit on an adult's lap (no seat of their own). Not counted in travelers and not in the quoted fare; the answer says how airlines charge them. | |
| arrive_after | No | HH:MM, local time at that airport. | |
| checked_bags | No | Checked bags per traveler (0-2), priced only for flights within the US and Canada (elsewhere the answer says the prices do not include them). Prices then include the bag fees: search_flights shows them as price_with_bags next to the fare; a calendar or bucket list prices every day with them. | |
| depart_after | No | HH:MM, local time at that airport. | |
| user_request | No | Optional, and it works in the traveler's favor. Quote the traveler's latest message about this trip exactly as they wrote it, in their wording, language and spelling, not a summary. SlickTrip runs its own travel parser on these words: when a search fails or comes back empty, it compares what the traveler said with the arguments sent and returns a corrected search, so you can fix it without asking them again. It has caught Cancun sent as MEX instead of CUN, and travelers dropped from the party. A summary loses exactly the details it checks. If the message only answers a question ("yes, the 20th"), quote the message where they asked for the trip. Send the same quote on every call for this request. Leave out anything not about the trip, and never include names, contact details, or payment or ID information. The words also help SlickTrip improve its search. | |
| arrive_before | No | HH:MM, local time at that airport. | |
| carry_on_bags | No | Carry-on bags per traveler (0-1). Prices then include the bag fees: search_flights shows them as price_with_bags next to the fare; a calendar or bucket list prices every day with them. | |
| depart_before | No | HH:MM, local time at that airport. | |
| lower_emissions | No | Only itineraries with lower emissions than is typical for the route. | |
| exclude_airlines | No | Leave out itineraries with any flight sold by these carriers (IATA codes, names or an alliance), by flight number or airline name: for 'not Gol' or 'avoid Air India'. | |
| trip_length_days | No | How many nights the traveler wants to stay. Round trips only. Every price in the calendar is for exactly this many nights. If the traveler has not told you how many nights, ask them. Do not pick a number for the traveler. | |
| max_layover_hours | No | Longest layover allowed at every connection, in hours (half hours allowed): for 'layovers no longer than 5 hours'. | |
| min_layover_hours | No | Shortest layover allowed at every connection, in hours (half hours allowed): for 'at least 2 hours to connect'. | |
| max_duration_hours | No | Longest itinerary to show, in hours. | |
| connecting_airports | No | Only itineraries that change planes at these airports (codes or city codes), nonstops included: for 'US connections only' name the hubs. | |
| exclude_connecting_airports | No | Leave out itineraries that change planes at these airports (codes or city codes). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | On an error: a machine-readable kind, e.g. unknown_place | |
| days | No | Items: depart_date, return_date, price_usd, day_of_week, low_price | |
| note | No | Next-step guidance or why no data | |
| field | No | On unknown_place: which argument (origin, destination, ...) | |
| query | No | The calendar query: origin, destination, cabin, travelers, trip_type, stops, month, airlines | |
| status | No | ok | no_data | error | sign_in_required | |
| message | No | Error or sign-in message from the server wrapper | |
| summary | No | Partner grid summary stats for the window | |
| search_url | No | slicktrip.com flights tab link | |
| suggestions | No | On unknown_place: places to offer the traveler, each with code, name, kind (airport, all airports in the city, nearby airport), city, country | |
| places_assumed | No | Place names this call resolved on its own, e.g. 'Portland = Portland, OR (PDX)'; tell the traveler |