Google Flights API

# Integrate HasData Google Flights API

## Task

Add the flight-search or deal-discovery function this project needs using HasData Google Flights API.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow the project's conventions and preserve unrelated code. No new SDK is required.
Choose the endpoint for the requested task; do not build both workflows unless needed.
Do not replace the REST integration with an MCP connection or a custom Google Flights scraper.

## References

Read the relevant endpoint documentation before implementing:

- Routes and itineraries: https://docs.hasdata.com/apis/google-travel/flights.md
- Natural-language deal search: https://docs.hasdata.com/apis/google-travel/flights-deals.md
- Error handling: https://docs.hasdata.com/api-codes.md
- Documentation index: https://docs.hasdata.com/llms.txt
- Full documentation (fallback): https://docs.hasdata.com/llms-full.txt

Start with the endpoint references. Use `llms.txt` to find additional pages.
Use `llms-full.txt` only when needed; extract relevant sections instead of loading everything into context.
If a `.md` reference is unavailable, try its HTML URL without `.md`.
If it is still unavailable, ask for the missing documentation rather than guessing.

## Optional agent skill

If the official `hasdata` skill is already available, use its relevant guidance.
Otherwise, if this agent supports skills, ask before installing it in this project:

```sh
npx skills add hasdata/agent-skills --skill hasdata
```

Run from the project directory and select the coding agent in use.
The `hasdata-cli` skill is not required. If installation is declined or unsupported, continue with the docs.
Flag conflicts between skill guidance and current API docs rather than guessing.

## Implementation

- Route search: `GET https://api.hasdata.com/scrape/google/flights`. Use documented `departureId`, `arrivalId`, and `outboundDate` for a dated route search. Airport identifiers can be IATA codes or supported location IDs.
- Set `type` explicitly: `oneWay`, `roundTrip`, or `multiCity`. A round trip requires `returnDate`; multi-city uses the documented `multiCityJson` structure. Implement only the trip types the project needs.
- For route search, keep dates in YYYY-MM-DD format and validate future dates and ordering. Preserve currency, passenger counts, and cabin class throughout a search and follow-up requests.
- Treat `bestFlights`, `otherFlights`, `priceInsights`, and `airports` as optional response blocks. Preserve returned itinerary prices, flight legs, layovers, and their local-time strings. Do not infer missing return-leg details.
- If needed, use a returned `departureToken` for return or onward flights, or `bookingToken` for booking options. Never combine these tokens. Each follow-up is a separate request; do not automatically expand every result.
- Deal discovery: `GET https://api.hasdata.com/scrape/google/flights-deals` with required `q` (natural-language travel request) and `departureId` (one uppercase three-letter IATA airport code, not a city name or a list). Read its own parameters; use a verified response fixture when available rather than reusing route-search field assumptions.
- For Deals, use `arrivalId` when the user needs documented structured filters. Google ignores those filters without an explicit destination; do not silently claim they were applied. Preserve returned dates, destination, duration, currency, and price basis together.
- Deals dates accept an exact date or a comma-separated date window. Its `returnDate`, `travelDuration`, and `tripLength` options are mutually exclusive; `returnDate` requires `outboundDate`. Implement only the documented combinations needed for the task.
- Preserve `searchInformation` and `flightDeals`. Each deal can contain `destination`, `outboundDate`, `returnDate`, `price`, `typicalPrice`, `discountPercent`, and `bookingLink`. Preserve currency and each deal’s dates; do not assume all suggestions cover the same stay or recalculate reported discounts. One-way deals can omit return dates.
- Treat an empty `flightDeals` array as a valid result. Do not silently relax the user's constraints or retry to force matches.
- Add only documented filters needed for the task. Avoid incompatible airline filters and handle opaque tokens without decoding or modifying them.
- Handle timeouts, documented errors, empty results, and missing optional price, baggage, emissions, or historical data. Unknown does not mean zero or false.
- Price alerts, scheduled monitoring, saved search history, and recommendations belong to this application. The API retrieves results; do not implement ticket purchases or promise guaranteed fares.
- Keep requests server-side. If there is no suitable server-side runtime, discuss options before changing the architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the project's existing environment or secret store and send it as `x-api-key`.
- If the key is missing before live verification, ask the user to configure it from https://app.hasdata.com/api-keys.
- Never ask the user to paste the key into chat. Check only that it is configured, without printing its value.
- Never put the key in browser code, logs, or version control. Add only a placeholder to example configuration.
- If using a local `.env` file, make sure it is gitignored.
- Send the key only to `https://api.hasdata.com`. Never forward it to documentation, Google, airline URLs, or redirects to another origin.

## Verification

- Add mocked tests for the chosen endpoint: success, empty results, missing optional blocks, documented errors, and parameter encoding. Test date validation and token handling only for the implemented workflow.
- Include a usage example and run local checks without paid API calls. If no verified response fixture is available, ask for one instead of inventing a schema.
- Only after explicit user approval and with a configured key, make one live verification request with agreed travel inputs. Successful requests consume credits, including empty results.
- Validate HTTP status, documented API status, and response structure. Do not automatically repeat paid requests to obtain data.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.