Pinpoint Flights

Search flights on Pinpoint Flights, a flight search with very deep filters: exact time windows, nonstop vs. price trade-offs, bags, fare rules, airlines to avoid, flexible dates and trip lengths, nearby airports, several destinations at once. Fill in only what the traveller said and leave everything else out (defaults apply). If something that changes the results is missing (dates, how long the stay is, an airport we can't place), no search runs: you get questions back to ask the traveller, then call again with the answers. Each traveller has 7 searches a day, so ask before searching when the request is vague, and don't run near-identical searches to compare: one search already prices many date combinations. Repeating a search from the last 24 hours is free. Results come with a link to the full results on pinpoint.flights, and each flight that can be booked has its own book_url: show the traveller the best match and every flight in each section (up to 10 in all), in rank order, each with its price, times, stops, airline and book_url, not just the top one or two; mention same-price swaps when a flight lists them; and give them the results link too, since booking happens there.

How to fill the fields (these are the rules the site's own assistant follows; where they say "readback", that means what you tell the traveller):

• Places: copy what the user said (city, airport code, country, region). Do not invent airport codes. If several destinations are named as alternatives ("Bali or Thailand"), list them all; the engine picks the cheapest. When the user names the airport they prefer in a city ("I strongly prefer DCA"), that airport is the place: don't also list the city, and don't describe a preference the filters can't hold.

• Dates: express them as intents relative to today (relative_days), as months (YYYY-MM), or as absolute dates only when the user gave one. Never compute a calendar date yourself from phrases like "next spring"; use kind=month with the months you mean, or ask. A month that has already passed this year means next year's (in September, "May or June" is May–June of next year); a date or month that is today or later means this year. Nobody books flights in the past, so never remark on it; just state the resolved dates ("May or June 2027"), never "(those months have passed)".

• Hard vs soft: "never / only / has to / must / can't" → hard (mode=hard, exclude, required). "prefer / rather not / ideally / would love / if it's less than X more" → soft with the premium the user stated (pct or usd). A soft preference with no stated premium gets premium=null; the engine applies a default and your readback must say so.

• Travellers: adults are 12+. Children aged 2–17 go in childrenAges with their ages (ask for ages only if they matter and are missing). A baby or infant under 2 is a lap infant (infants) unless the user says it gets its own seat or a car seat (infantsInSeat).

• Money is per person unless the user says "total" or "for the family/group".

• Bags: if the user doesn't mention bags, use carryOn=1, checked=0 (not -1) and say so in the readback. Bags are pooled only when the user speaks of the group's checked bags ("two bags for the family"): then checked is the group total and pooled=true, but carryOn is still per traveller ("everyone has a carry-on" = carryOn 1).

• "Sit together", "seats next to each other", "pick our seats" → excludeBasicEconomy=true (basic fares don't allow seat selection) and fare.seatSelection=required.

• Trip length: never guess one. A round trip with no stated length, return date or return window leaves tripLength and the return dates unstated and asks how long they want to stay (field dates.tripLength); the readback must not assume a length. If the description says something about the stay that doesn't settle it, the question names it and why ("You said about two weeks, but also back before the 9th, which allows 6 days at most. Which matters more?"). If the user gives a preferred length and a maximum but no minimum, leave minDays null and ask what the shortest acceptable trip is. A short trip described by weekdays or as "a long weekend" ("leave Thursday or Friday, back Sunday or Monday") gets the tripLength that fits, here minDays 2 and maxDays 4, so the engine never pairs a Thursday with a Monday ten days later.

• Weekday arithmetic: if fixed outbound and return weekdays are combined with a trip length that cannot satisfy both ("leave Saturday, back Sunday, 10 days"), keep both as stated: the weekdays, and the length as tripLength.preferredDays with minDays and maxDays unstated. Don't add a question of your own about it: the engine asks which one gives. The readback says the two don't fit together and that I'll ask.

• Time-of-day windows: if the user gives a window without saying which direction, set it on outbound and set timesApplyToBothDirections=null and ask.

• Hard vs ideal times: "no earlier than / not past / the earliest I can leave / shouldn't arrive after" are hard bounds (departNotBefore, arriveNotAfter…). "Ideally / around / preferably" times are the ideal window, never hard: "ideally around 2pm" = idealArriveFrom 13:00, idealArriveTo 15:00; "ideally 8pm to 11pm" = idealDepartFrom 20:00, idealDepartTo 23:00.

• Clock times without AM or PM: "7:59", "at 8" or "leaves 7:40" with no AM/PM is ambiguous, including the times of a flight the traveller mentions for reference ("my flight departs 7:59"). Don't pick one and don't guess from what seems likely: ask ("Is 7:59 in the morning or the evening?", field dates.timeOfDay). It is settled only when the traveller writes AM or PM, uses 24-hour time somewhere in the request (an hour of 13 or more, or a leading zero like 07:30), or says it in words ("in the morning", "tonight", "noon"). A time given with a flight number needs no question: the flight number settles it (see Exact flights).

• Exact flights: when the traveller wants to be on a specific flight ("ideally the same flight as my DL2729", "the 7am Delta, DL1003, if possible"), put its flight number in exactFlights for that direction. It is soft: premium only if they state one ("much rather" = pct 30), zeros otherwise (the engine's default applies). "A little earlier or later is fine if cheaper" needs nothing more: the named flight ranks first and the others still show. A flight that is only background is not a preference: one they say is fine but not needed ("the exact same flight would also be fine"), or one they want to get away from (a layover they want to avoid goes in the stop or layover fields).

• Times tied to one date: "the earliest I can leave is 7pm on the 27th" is a return window with onlyOnDate set to that date (an absolute date the user gave). It does not apply to other dates: when the user also allows a fallback date ("or the 28th if needed"), the window must carry onlyOnDate so flights on the fallback date are not held to it.

• Blackouts are only dates the traveller cannot fly at all that would otherwise be inside the departure or return windows. Days spent working or busy at the destination are already outside the return window; don't list them. Never black out a day the traveller can fly part of; that is a time window with onlyOnDate.

• A preferred date inside a date window ("I'd much rather leave the 27th; the 28th only if it's much cheaper") is a soft weekday preference for that date's weekday (returnDays or outboundDays, mode=soft) with the premium. The readback may only describe preferences that are set in the intent.

• arriveBy is for a deadline at the destination ("must be there by 9am on the 14th") that should pull the departure date earlier. When the departure date is already fixed, an arrival time limit is outboundTimes.arriveNotAfter only; leave arriveBy unstated.

• Stops: "nonstop only / direct only / no connections" → nonstop.mode=hard and maxStops=0. "Prefer nonstop / no layovers if possible / nonstop strongly preferred unless much cheaper" → nonstop.mode=soft with the premium (the premium over a one-stop flight) and maxStops=-1, so connections still show when they are much cheaper. When stops aren't mentioned, leave nonstop unstated: the engine's default preference applies.

• Strength of a soft preference with no number: plain "prefer" → zeros in the premium (the engine default applies). Stressed ("strongly prefer", "much rather", "unless it's much cheaper", "much much cheaper") → pct 30.

• Ranking: the engine defaults to "balanced" common sense: it values the traveller's time at about $25 per hour per person against the fastest option and mildly dislikes stops and long layovers, so a slightly dearer nonstop or much shorter itinerary ranks first (the cheaper one is still shown). Set rankBy=cheapest only when the user says they want the absolute cheapest, that price is all that matters, or that duration/stops don't matter; otherwise rankBy=unstated. Mention ranking in the readback only when it is "cheapest".