swoop-flights 0.1.0__tar.gz

swoop_flights-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Hypothesis
+.hypothesis/
+
+# Test / coverage
+.pytest_cache/
+htmlcov/
+.coverage
+
+# Environment
+.env
+.env.*
+
+# IDE
+.vscode/
+.idea/

swoop_flights-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Saraswat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swoop_flights-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: swoop-flights
+Version: 0.1.0
+Summary: Google Flights price scraper. Search flights programmatically via the same RPC endpoints the web app uses.
+Project-URL: Homepage, https://github.com/saraswatayu/swoop
+Project-URL: Issues, https://github.com/saraswatayu/swoop/issues
+Author: Ayush Saraswat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: flights,google-flights,prices,scraper,travel
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: primp>=1.0.0
+Requires-Dist: protobuf>=4.0.0
+Provides-Extra: validation
+Requires-Dist: airportsdata>=1.3.0; extra == 'validation'
+Description-Content-Type: text/markdown
+
+# swoop
+
+Google Flights price scraper. Search flights programmatically using the same RPC endpoints the Google Flights web app uses.
+
+```python
+from swoop import search
+
+results = search("JFK", "LAX", "2026-06-01")
+for flight in results.best:
+    airline = ", ".join(flight.airline_names)
+    print(f"${flight.price} — {airline}")
+```
+
+## Install
+
+```bash
+pip install swoop-flights
+```
+
+## Usage
+
+### One-way search
+
+```python
+from swoop import search
+
+results = search("SFO", "JFK", "2026-06-15")
+
+# results.best  — top-ranked flights
+# results.other — remaining flights
+for flight in results.best:
+    print(f"${flight.price}")
+    print(f"  {flight.departure_airport} → {flight.arrival_airport}")
+    print(f"  {flight.airline_names}, {flight.stop_count} stops")
+    print(f"  {flight.travel_time} min total")
+```
+
+### Roundtrip search
+
+```python
+results = search("SFO", "JFK", "2026-06-15", return_date="2026-06-22")
+# Price in results is the roundtrip total
+```
+
+### Cabin class and filters
+
+```python
+from swoop import search, SORT_CHEAPEST
+
+results = search(
+    "LAX", "NRT", "2026-06-15",
+    cabin="business",       # economy, premium-economy, business, first
+    max_stops=0,            # nonstop only
+    sort=SORT_CHEAPEST,     # cheapest first
+    airlines=["NH", "JL"],  # filter to specific carriers
+)
+```
+
+### Time window filtering
+
+```python
+results = search(
+    "JFK", "LHR", "2026-06-15",
+    earliest_departure=8,   # depart after 8am
+    latest_departure=14,    # depart before 2pm
+)
+```
+
+### Booking details (fare options)
+
+```python
+from swoop import search, get_booking_results
+
+results = search("JFK", "LAX", "2026-06-15")
+itinerary = results.best[0]
+
+# Get fare tiers — just pass the itinerary
+options = get_booking_results(itinerary)
+
+for opt in options:
+    print(f"${opt.price} — {opt.brand_label} ({opt.fare_family})")
+```
+
+You can also pass a booking token string with explicit parameters:
+
+```python
+options = get_booking_results(
+    itinerary.booking_token,
+    origin="JFK",
+    destination="LAX",
+    date="2026-06-15",
+    selected_legs=[
+        [
+            flight.departure_airport,
+            f"{flight.departure_date[0]}-{flight.departure_date[1]:02d}-{flight.departure_date[2]:02d}",
+            flight.arrival_airport,
+            None,
+            flight.airline,
+            flight.flight_number,
+        ]
+        for flight in itinerary.flights
+    ],
+)
+```
+
+### Retry and timeout
+
+```python
+# Retry up to 3 times on HTTP 429 (rate limit) with exponential backoff
+results = search("JFK", "LAX", "2026-06-15", retries=3, timeout=90)
+
+# Same for booking results
+options = get_booking_results(itinerary, retries=2, timeout=60)
+```
+
+### Flight details
+
+Each `Itinerary` contains detailed segment data:
+
+```python
+results = search("JFK", "LAX", "2026-06-15")
+for itinerary in results.best:
+    for flight in itinerary.flights:
+        print(f"{flight.airline} {flight.flight_number}")
+        print(f"  {flight.departure_airport} → {flight.arrival_airport}")
+        print(f"  Aircraft: {flight.aircraft}")
+        print(f"  Legroom: {flight.legroom}")
+        if flight.co2_grams:
+            print(f"  CO₂: {flight.co2_grams}g")
+
+    if itinerary.carbon_emissions:
+        ce = itinerary.carbon_emissions
+        print(f"  Route emissions: {ce.difference_percent}% vs typical")
+
+    if results.price_range:
+        print(f"  Price range: ${results.price_range.low}–${results.price_range.high}")
+```
+
+## Error handling
+
+```python
+from swoop import search, SwoopHTTPError, SwoopRateLimitError, SwoopParseError
+
+try:
+    results = search("JFK", "LAX", "2026-06-15")
+except SwoopRateLimitError:
+    print("Rate limited — wait a few minutes")
+except SwoopHTTPError as e:
+    print(f"HTTP {e.status_code}")
+except SwoopParseError as e:
+    print(f"Parse error: {e}")
+```
+
+## API reference
+
+### `search(origin, destination, date, **kwargs)`
+
+Search Google Flights and return a `SearchResult`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `origin` | `str` | required | Origin IATA code |
+| `destination` | `str` | required | Destination IATA code |
+| `date` | `str` | required | Departure date (`YYYY-MM-DD`) |
+| `return_date` | `str \| None` | `None` | Return date for roundtrip |
+| `cabin` | `str` | `"economy"` | `economy`, `premium-economy`, `business`, `first` |
+| `adults` | `int` | `1` | Number of adults |
+| `max_stops` | `int \| None` | `None` | `None`=any, `0`=nonstop, `1`=1 stop, `2`=2 stops |
+| `sort` | `int` | `SORT_DEPARTURE_TIME` | Sort order constant |
+| `airlines` | `list[str] \| None` | `None` | Filter by airline codes |
+| `include_basic_economy` | `bool` | `False` | Include basic economy fares |
+| `timeout` | `int` | `90` | HTTP timeout in seconds |
+| `retries` | `int` | `0` | Retries on HTTP 429 with exponential backoff |
+
+Returns `SearchResult | None`. `None` means no results found.
+
+### `get_booking_results(itinerary_or_token, **kwargs)`
+
+Get fare options for a specific itinerary. Pass an `Itinerary` object directly, or a booking token string with explicit `origin`, `destination`, `date`, and `selected_legs`. Returns `list[BookingOption]` with `price`, `brand_label`, `brand_code`, `fare_family`, etc. `BookingOption` supports both attribute access (`opt.price`) and dict-style access (`opt["price"]`, `opt.get("price")`).
+
+### Result types
+
+- **`SearchResult`** — `best: list[Itinerary]`, `other: list[Itinerary]`, `price_range: PriceRange | None`
+- **`Itinerary`** — Full itinerary with `price`, `flights`, `layovers`, `travel_time`, `booking_token`, `carbon_emissions`
+- **`Flight`** — Segment details: `airline`, `flight_number`, `aircraft`, `legroom`, `co2_grams`, `amenities`
+- **`Layover`** — Stop info: `minutes`, airports, `is_overnight`
+- **`CarbonEmissions`** — `this_flight_grams`, `typical_for_route_grams`, `difference_percent`
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `SORT_TOP` | `1` | Google's default ranking |
+| `SORT_CHEAPEST` | `2` | Cheapest first |
+| `SORT_DEPARTURE_TIME` | `3` | By departure time |
+| `SORT_ARRIVAL_TIME` | `4` | By arrival time |
+| `SORT_DURATION` | `5` | Shortest first |
+
+## Pricing notes
+
+Use `itinerary.price` to get the USD price as an integer.
+
+By default, `search()` excludes basic economy fares so prices reflect Main Cabin. Pass `include_basic_economy=True` to include them:
+
+```python
+results = search("JFK", "LAX", "2026-06-15", include_basic_economy=True)
+```
+
+## How it works
+
+Swoop uses Google Flights' internal `GetShoppingResults` and `GetBookingResults` RPC endpoints — the same ones the web app calls when you search for flights. Requests are serialized as nested JSON payloads and sent via HTTP POST with browser impersonation (via [primp](https://github.com/deedy5/primp)).
+
+Responses are decoded from nested list structures into typed Python dataclasses.
+
+## Dependencies
+
+- **[primp](https://github.com/deedy5/primp)** — HTTP client with browser TLS impersonation
+- **[protobuf](https://pypi.org/project/protobuf/)** — Protocol buffer serialization
+
+## License
+
+MIT

swoop_flights-0.1.0/README.md

@@ -0,0 +1,222 @@
+# swoop
+
+Google Flights price scraper. Search flights programmatically using the same RPC endpoints the Google Flights web app uses.
+
+```python
+from swoop import search
+
+results = search("JFK", "LAX", "2026-06-01")
+for flight in results.best:
+    airline = ", ".join(flight.airline_names)
+    print(f"${flight.price} — {airline}")
+```
+
+## Install
+
+```bash
+pip install swoop-flights
+```
+
+## Usage
+
+### One-way search
+
+```python
+from swoop import search
+
+results = search("SFO", "JFK", "2026-06-15")
+
+# results.best  — top-ranked flights
+# results.other — remaining flights
+for flight in results.best:
+    print(f"${flight.price}")
+    print(f"  {flight.departure_airport} → {flight.arrival_airport}")
+    print(f"  {flight.airline_names}, {flight.stop_count} stops")
+    print(f"  {flight.travel_time} min total")
+```
+
+### Roundtrip search
+
+```python
+results = search("SFO", "JFK", "2026-06-15", return_date="2026-06-22")
+# Price in results is the roundtrip total
+```
+
+### Cabin class and filters
+
+```python
+from swoop import search, SORT_CHEAPEST
+
+results = search(
+    "LAX", "NRT", "2026-06-15",
+    cabin="business",       # economy, premium-economy, business, first
+    max_stops=0,            # nonstop only
+    sort=SORT_CHEAPEST,     # cheapest first
+    airlines=["NH", "JL"],  # filter to specific carriers
+)
+```
+
+### Time window filtering
+
+```python
+results = search(
+    "JFK", "LHR", "2026-06-15",
+    earliest_departure=8,   # depart after 8am
+    latest_departure=14,    # depart before 2pm
+)
+```
+
+### Booking details (fare options)
+
+```python
+from swoop import search, get_booking_results
+
+results = search("JFK", "LAX", "2026-06-15")
+itinerary = results.best[0]
+
+# Get fare tiers — just pass the itinerary
+options = get_booking_results(itinerary)
+
+for opt in options:
+    print(f"${opt.price} — {opt.brand_label} ({opt.fare_family})")
+```
+
+You can also pass a booking token string with explicit parameters:
+
+```python
+options = get_booking_results(
+    itinerary.booking_token,
+    origin="JFK",
+    destination="LAX",
+    date="2026-06-15",
+    selected_legs=[
+        [
+            flight.departure_airport,
+            f"{flight.departure_date[0]}-{flight.departure_date[1]:02d}-{flight.departure_date[2]:02d}",
+            flight.arrival_airport,
+            None,
+            flight.airline,
+            flight.flight_number,
+        ]
+        for flight in itinerary.flights
+    ],
+)
+```
+
+### Retry and timeout
+
+```python
+# Retry up to 3 times on HTTP 429 (rate limit) with exponential backoff
+results = search("JFK", "LAX", "2026-06-15", retries=3, timeout=90)
+
+# Same for booking results
+options = get_booking_results(itinerary, retries=2, timeout=60)
+```
+
+### Flight details
+
+Each `Itinerary` contains detailed segment data:
+
+```python
+results = search("JFK", "LAX", "2026-06-15")
+for itinerary in results.best:
+    for flight in itinerary.flights:
+        print(f"{flight.airline} {flight.flight_number}")
+        print(f"  {flight.departure_airport} → {flight.arrival_airport}")
+        print(f"  Aircraft: {flight.aircraft}")
+        print(f"  Legroom: {flight.legroom}")
+        if flight.co2_grams:
+            print(f"  CO₂: {flight.co2_grams}g")
+
+    if itinerary.carbon_emissions:
+        ce = itinerary.carbon_emissions
+        print(f"  Route emissions: {ce.difference_percent}% vs typical")
+
+    if results.price_range:
+        print(f"  Price range: ${results.price_range.low}–${results.price_range.high}")
+```
+
+## Error handling
+
+```python
+from swoop import search, SwoopHTTPError, SwoopRateLimitError, SwoopParseError
+
+try:
+    results = search("JFK", "LAX", "2026-06-15")
+except SwoopRateLimitError:
+    print("Rate limited — wait a few minutes")
+except SwoopHTTPError as e:
+    print(f"HTTP {e.status_code}")
+except SwoopParseError as e:
+    print(f"Parse error: {e}")
+```
+
+## API reference
+
+### `search(origin, destination, date, **kwargs)`
+
+Search Google Flights and return a `SearchResult`.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `origin` | `str` | required | Origin IATA code |
+| `destination` | `str` | required | Destination IATA code |
+| `date` | `str` | required | Departure date (`YYYY-MM-DD`) |
+| `return_date` | `str \| None` | `None` | Return date for roundtrip |
+| `cabin` | `str` | `"economy"` | `economy`, `premium-economy`, `business`, `first` |
+| `adults` | `int` | `1` | Number of adults |
+| `max_stops` | `int \| None` | `None` | `None`=any, `0`=nonstop, `1`=1 stop, `2`=2 stops |
+| `sort` | `int` | `SORT_DEPARTURE_TIME` | Sort order constant |
+| `airlines` | `list[str] \| None` | `None` | Filter by airline codes |
+| `include_basic_economy` | `bool` | `False` | Include basic economy fares |
+| `timeout` | `int` | `90` | HTTP timeout in seconds |
+| `retries` | `int` | `0` | Retries on HTTP 429 with exponential backoff |
+
+Returns `SearchResult | None`. `None` means no results found.
+
+### `get_booking_results(itinerary_or_token, **kwargs)`
+
+Get fare options for a specific itinerary. Pass an `Itinerary` object directly, or a booking token string with explicit `origin`, `destination`, `date`, and `selected_legs`. Returns `list[BookingOption]` with `price`, `brand_label`, `brand_code`, `fare_family`, etc. `BookingOption` supports both attribute access (`opt.price`) and dict-style access (`opt["price"]`, `opt.get("price")`).
+
+### Result types
+
+- **`SearchResult`** — `best: list[Itinerary]`, `other: list[Itinerary]`, `price_range: PriceRange | None`
+- **`Itinerary`** — Full itinerary with `price`, `flights`, `layovers`, `travel_time`, `booking_token`, `carbon_emissions`
+- **`Flight`** — Segment details: `airline`, `flight_number`, `aircraft`, `legroom`, `co2_grams`, `amenities`
+- **`Layover`** — Stop info: `minutes`, airports, `is_overnight`
+- **`CarbonEmissions`** — `this_flight_grams`, `typical_for_route_grams`, `difference_percent`
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `SORT_TOP` | `1` | Google's default ranking |
+| `SORT_CHEAPEST` | `2` | Cheapest first |
+| `SORT_DEPARTURE_TIME` | `3` | By departure time |
+| `SORT_ARRIVAL_TIME` | `4` | By arrival time |
+| `SORT_DURATION` | `5` | Shortest first |
+
+## Pricing notes
+
+Use `itinerary.price` to get the USD price as an integer.
+
+By default, `search()` excludes basic economy fares so prices reflect Main Cabin. Pass `include_basic_economy=True` to include them:
+
+```python
+results = search("JFK", "LAX", "2026-06-15", include_basic_economy=True)
+```
+
+## How it works
+
+Swoop uses Google Flights' internal `GetShoppingResults` and `GetBookingResults` RPC endpoints — the same ones the web app calls when you search for flights. Requests are serialized as nested JSON payloads and sent via HTTP POST with browser impersonation (via [primp](https://github.com/deedy5/primp)).
+
+Responses are decoded from nested list structures into typed Python dataclasses.
+
+## Dependencies
+
+- **[primp](https://github.com/deedy5/primp)** — HTTP client with browser TLS impersonation
+- **[protobuf](https://pypi.org/project/protobuf/)** — Protocol buffer serialization
+
+## License
+
+MIT

swoop_flights-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "swoop-flights"
+dynamic = ["version"]
+description = "Google Flights price scraper. Search flights programmatically via the same RPC endpoints the web app uses."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Ayush Saraswat" }]
+keywords = ["google-flights", "flights", "travel", "scraper", "prices"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Typing :: Typed",
+]
+dependencies = [
+    "primp>=1.0.0",
+    "protobuf>=4.0.0",
+]
+
+[project.optional-dependencies]
+validation = ["airportsdata>=1.3.0"]
+
+[project.urls]
+Homepage = "https://github.com/saraswatayu/swoop"
+Issues = "https://github.com/saraswatayu/swoop/issues"
+
+[tool.hatch.version]
+path = "swoop/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["swoop"]
+
+[tool.hatch.build.targets.sdist]
+include = ["swoop/", "README.md", "LICENSE"]
+
+[tool.pyright]
+pythonVersion = "3.10"
+typeCheckingMode = "basic"
+exclude = ["swoop/flights_pb2.py", "tests/"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "live: integration tests that hit real Google Flights API (deselect with -m 'not live')",
+]
+
+[tool.mutmut]
+paths_to_mutate = "swoop/decoder.py,swoop/rpc.py,swoop/_validate.py,swoop/_booking.py"
+tests_dir = "tests/"
+runner = "python -m pytest tests/ -x --ignore=tests/test_booking_options_corpus.py --ignore=tests/test_booking_option_schema_hypotheses.py --ignore=tests/test_corpus_matrix_tools.py --ignore=tests/test_booking_option_field_explorer.py -m 'not live' -q"