# Stopover Planner

> Live Google Flights search API. Real GBP prices with a Google Flights booking link on every flight. Unique endpoints: multi-day stopover itineraries priced as one trip, country-wide fare sweeps, explore-anywhere cheapest destinations, and point-to-point fares.

Subscribe on RapidAPI: https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner (free tier available, no sales call). Send X-RapidAPI-Key and X-RapidAPI-Host: stopover-planner.p.rapidapi.com. All endpoints accept JSON bodies; all prices are GBP with a numeric priceValue field. Every dates / deadlineDates array takes 1 to 31 real YYYY-MM-DD calendar dates per request; outside that you get a 400.

Every search runs live against Google Flights, so calls take seconds (5 to 40 depending on scope). Any search accepts "async": true and returns a jobId immediately; poll GET /jobs/{id} until status is "done".

## Endpoints

- [POST /search/bonus](https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner): multi-day stopover itineraries. Body: {"origin":"London","destination":"Tokyo","deadlineDates":["2026-09-20"],"layoverDays":3,"async":true}. Returns events: ITINERARY_FOUND with leg1, leg2, totalPrice, layoverDurationHours; each leg has price, priceValue, bookingLink.
- [POST /search/country](https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner): cheapest fares from one origin to every city in a country. Body: {"origin":"London","country":"Spain","dates":["2026-09-15"]}.
- [POST /search/explore](https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner): cheapest destinations anywhere from an origin. Body: {"origin":"London","dates":["2026-09-15"]}.
- [POST /search/direct](https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner): point-to-point fares across dates. Body: {"origin":"London","destination":"Madrid","dates":["2026-09-15"]}. Response: results[].flights[] with airline, price ("£22"), priceValue (22), duration, stops, times, bookingLink; plus failedDates[].
- [GET /jobs/{id}](https://rapidapi.com/stopover-labs-stopover-labs-default/api/stopover-planner): poll an async search until done.

## Machine-readable

- [OpenAPI spec](/openapi.yaml): full schema with examples.
- [MCP server](https://mcp.stopovercity.com/mcp): streamable-HTTP MCP endpoint exposing the searches as tools (search_stopover_itineraries, search_flights, search_country_sweep, search_explore_anywhere, get_job_result). Configure your RapidAPI key as an X-RapidAPI-Key header.

## Optional

- [Consumer product](https://stopovercity.com): the same engine powering a stopover-holiday finder.