Find Dates - Jinko Platform

Answers “when should I fly?” for a known route. Takes the same inputs as Flight Calendar but returns up to ten cheapest itineraries — one per (departure, return) date-pair — spread across the requested departure window, so the user gets a diverse shortlist rather than ten near-adjacent cheapest days. Cache-backed; no live pricing. Each result includes an offer token you can pass into a live price check or directly into a trip.

Tool description (what the LLM sees)

Find the best date options for a known origin and destination using cached pricing. Takes the SAME inputs as flight_calendar, but returns up to ten cheapest itineraries — one per (departure, return) date-pair — spread across the requested departure window, so the user sees a diverse set of "when should I fly?" options rather than the full per-date list.

WHEN TO USE THIS TOOL:
- The user knows the route (origin AND destination) and is flexible on WHEN, and wants a short, spread-out shortlist of the best date options.
- Examples: "When is the cheapest time to fly Paris → New York in June?", "Best weekends to go from London to Lisbon next month", "Give me a few good date options for a week in Tokyo".

WHEN TO USE flight_calendar INSTEAD:
- The user wants the full price-per-date list / calendar grid for a route, not a curated shortlist.

WHEN TO USE flight_search INSTEAD:
- The user has committed to EXACT dates (single departure AND single return). flight_search hits live pricing and is the step before booking.

IMPORTANT:
  All dates MUST be in the future. Never use past dates.
  Origin and destination must be IATA city codes by default, or IATA airport codes if the user specifies them.
  By default search roundtrip unless the user explicitly asks for one-way (trip_type="oneway").

Flow: find_dates → flight_search (price-check the chosen dates) → trip → book

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 date-pairs to return (1-100). Default 20.

​Parameters

Parameters