Add RoundTripResult model and search_round_trip to all providers

- models.py: Add RoundTripResult(outbound, inbound, total_price, currency)
- duffel.py: Add _convert_offer_slice() and DuffelProvider.search_round_trip()
  using two-slice offer_requests API for native round-trip fares
- google.py: Add GoogleProvider.search_round_trip() using TripType.ROUND_TRIP
  with paired outbound/return FlightSegments
- search.py: Add SearchEngine.search_round_trip() with caching, max_price
  filtering, and sorted-by-total_price output

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: federicodeponte

src/opensky/models.py

@@ -77,6 +77,13 @@ class FlightResult(BaseModel):
     booking_url: str = ""
 
 
+class RoundTripResult(BaseModel):
+    outbound: FlightResult
+    inbound: FlightResult
+    total_price: float
+    currency: str
+
+
 class ScoredFlight(BaseModel):
     flight: FlightResult
     origin: str

src/opensky/providers/duffel.py

@@ -5,7 +5,7 @@
 import httpx
 from ratelimit import limits, sleep_and_retry
 
-from opensky.models import FlightLeg, FlightResult
+from opensky.models import FlightLeg, FlightResult, RoundTripResult
 from opensky.providers import parse_iso_duration
 
 log = logging.getLogger(__name__)
@@ -20,6 +20,47 @@
 }
 
 
+def _convert_offer_slice(offer: dict, slice_index: int, currency: str) -> FlightResult:
+    """Extract a single slice from a Duffel offer as a FlightResult (price=0, use offer total)."""
+    offer_currency = offer.get("total_currency", currency)
+    slices = offer.get("slices", [])
+    if slice_index >= len(slices):
+        return FlightResult(price=0, currency=offer_currency, duration_minutes=0, stops=0, legs=[], provider="duffel")
+
+    slc = slices[slice_index]
+    legs: list[FlightLeg] = []
+    total_duration = 0
+
+    for seg in slc.get("segments", []):
+        dep = seg.get("departing_at", "")
+        arr = seg.get("arriving_at", "")
+        dur = parse_iso_duration(seg.get("duration", ""))
+        total_duration += dur
+
+        carrier = seg.get("operating_carrier", {})
+        airline = carrier.get("iata_code", seg.get("marketing_carrier", {}).get("iata_code", ""))
+        flight_num = seg.get("operating_carrier_flight_number") or seg.get("marketing_carrier_flight_number") or ""
+
+        legs.append(FlightLeg(
+            airline=airline,
+            flight_number=flight_num,
+            departure_airport=seg.get("origin", {}).get("iata_code", ""),
+            arrival_airport=seg.get("destination", {}).get("iata_code", ""),
+            departure_time=dep,
+            arrival_time=arr,
+            duration_minutes=dur,
+        ))
+
+    return FlightResult(
+        price=0,
+        currency=offer_currency,
+        duration_minutes=total_duration,
+        stops=max(len(legs) - 1, 0),
+        legs=legs,
+        provider="duffel",
+    )
+
+
 def _convert_offer(offer: dict, currency: str) -> FlightResult:
     """Convert a Duffel offer dict to a FlightResult."""
     price = float(offer.get("total_amount", 0))
@@ -118,5 +159,55 @@ def search(
 
         return results
 
+    @sleep_and_retry
+    @limits(calls=10, period=1)
+    def search_round_trip(
+        self,
+        origin: str,
+        dest: str,
+        outbound_date: str,
+        return_date: str,
+        cabin: str,
+        currency: str,
+        max_stops: int | None,
+    ) -> list[RoundTripResult]:
+        cabin_class = CABIN_MAP.get(cabin, "economy")
+
+        payload = {
+            "data": {
+                "slices": [
+                    {"origin": origin, "destination": dest, "departure_date": outbound_date},
+                    {"origin": dest, "destination": origin, "departure_date": return_date},
+                ],
+                "passengers": [{"type": "adult"}],
+                "cabin_class": cabin_class,
+                "currency": currency,
+                "return_offers": True,
+                "max_connections": max_stops if max_stops is not None else 2,
+            }
+        }
+
+        resp = self._client.post("/air/offer_requests", json=payload)
+        resp.raise_for_status()
+        data = resp.json().get("data", {})
+        offers = data.get("offers", [])
+
+        results: list[RoundTripResult] = []
+        for offer in offers:
+            total_price = float(offer.get("total_amount", 0))
+            offer_currency = offer.get("total_currency", currency)
+            outbound = _convert_offer_slice(offer, 0, offer_currency)
+            inbound = _convert_offer_slice(offer, 1, offer_currency)
+            if max_stops is not None and (outbound.stops > max_stops or inbound.stops > max_stops):
+                continue
+            results.append(RoundTripResult(
+                outbound=outbound,
+                inbound=inbound,
+                total_price=total_price,
+                currency=offer_currency,
+            ))
+
+        return results
+
     def close(self) -> None:
         self._client.close()

src/opensky/providers/google.py

@@ -10,8 +10,9 @@
     SeatType,
     SearchFlights,
     SortBy,
+    TripType,
 )
-from opensky.models import FlightLeg, FlightResult
+from opensky.models import FlightLeg, FlightResult, RoundTripResult
 
 SEAT_MAP: dict[str, SeatType] = {
     "economy": SeatType.ECONOMY,
@@ -104,6 +105,55 @@ def search(
             return []
         return [_convert_result(r, currency) for r in raw_results]
 
+    def search_round_trip(
+        self,
+        origin: str,
+        dest: str,
+        outbound_date: str,
+        return_date: str,
+        cabin: str,
+        currency: str,
+        max_stops: int | None,
+    ) -> list[RoundTripResult]:
+        seat = SEAT_MAP.get(cabin, SeatType.ECONOMY)
+        stops = STOPS_MAP.get(max_stops, MaxStops.ANY)
+        filters = FlightSearchFilters(
+            trip_type=TripType.ROUND_TRIP,
+            flight_segments=[
+                FlightSegment(
+                    departure_airport=[[origin, 0]],
+                    arrival_airport=[[dest, 0]],
+                    travel_date=outbound_date,
+                ),
+                FlightSegment(
+                    departure_airport=[[dest, 0]],
+                    arrival_airport=[[origin, 0]],
+                    travel_date=return_date,
+                ),
+            ],
+            passenger_info=PassengerInfo(adults=1),
+            seat_type=seat,
+            stops=stops,
+            sort_by=SortBy.CHEAPEST,
+        )
+        api = self._get_api()
+        raw: list[tuple] = api.search(filters) or []  # type: ignore[assignment]
+        results: list[RoundTripResult] = []
+        for pair in raw:
+            if not isinstance(pair, tuple) or len(pair) != 2:
+                continue
+            out_raw, in_raw = pair
+            outbound = _convert_result(out_raw, currency)
+            inbound = _convert_result(in_raw, currency)
+            total_price = outbound.price + inbound.price
+            results.append(RoundTripResult(
+                outbound=outbound,
+                inbound=inbound,
+                total_price=total_price,
+                currency=currency,
+            ))
+        return results
+
     def close(self) -> None:
         if self._api:
             self._api.close()

src/opensky/search.py

@@ -8,7 +8,7 @@
 
 from opensky import cache
 from opensky.config import ScanConfig, VALID_CABINS, VALID_STOPS
-from opensky.models import FlightLeg, FlightResult, RiskLevel, ScoredFlight
+from opensky.models import FlightLeg, FlightResult, RiskLevel, RoundTripResult, ScoredFlight
 from opensky.providers import FlightProvider, configured_providers
 from opensky.safety import check_route
 
@@ -284,6 +284,54 @@ def search_scored_report(
             failed_providers=search_report.failed_providers,
         )
 
+    def search_round_trip(
+        self,
+        origin: str,
+        dest: str,
+        outbound_date: str,
+        return_date: str,
+        max_price: float = 0,
+    ) -> list[RoundTripResult]:
+        all_results: list[RoundTripResult] = []
+
+        for provider in self._providers:
+            if not hasattr(provider, "search_round_trip"):
+                continue
+            ck = cache.cache_key(
+                f"rt:{origin}", dest, f"{outbound_date}:{return_date}",
+                seat=self.seat, currency=self.currency,
+                stops=self.max_stops, provider=provider.name,
+            )
+            if self.use_cache:
+                cached = cache.get(ck)
+                if cached is not None:
+                    all_results.extend(cached)
+                    continue
+
+            try:
+                results = provider.search_round_trip(
+                    origin, dest, outbound_date, return_date,
+                    cabin=self.seat,
+                    currency=self.currency,
+                    max_stops=self.max_stops,
+                )
+            except Exception as exc:
+                log.warning(
+                    "Provider %s round-trip failed for %s->%s %s/%s: %s",
+                    provider.name, origin, dest, outbound_date, return_date, exc,
+                )
+                continue
+
+            if self.use_cache:
+                cache.put(ck, results)
+            all_results.extend(results)
+
+        if max_price > 0:
+            all_results = [r for r in all_results if r.total_price <= max_price]
+
+        all_results.sort(key=lambda r: r.total_price)
+        return all_results
+
     def scan(
         self,
         config: ScanConfig,