Metadata-Version: 2.4
Name: viajante
Version: 1.4.7
Summary: Flight and hotel search for the terminal, Python, and AI assistants.
Author: viajante contributors
License: MIT
Project-URL: Homepage, https://github.com/felipebasurto/viajante
Project-URL: Repository, https://github.com/felipebasurto/viajante
Project-URL: Documentation, https://github.com/felipebasurto/viajante/blob/main/docs/usage.md
Project-URL: Issues, https://github.com/felipebasurto/viajante/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: airportsdata>=20260315
Requires-Dist: curl-cffi>=0.16.0
Requires-Dist: selectolax>=0.3.25
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.14.1; extra == "mcp"
Provides-Extra: browser
Requires-Dist: playwright==1.60.0; extra == "browser"
Dynamic: license-file

# Viajante

Flight and hotel search for the terminal, Python, and AI assistants.

[![PyPI](https://img.shields.io/pypi/v/viajante.svg)](https://pypi.org/project/viajante/)
[![npm](https://img.shields.io/npm/v/@viajante/mcp.svg)](https://www.npmjs.com/package/@viajante/mcp)
[![Tests](https://github.com/felipebasurto/viajante/actions/workflows/test.yml/badge.svg)](https://github.com/felipebasurto/viajante/actions/workflows/test.yml)

Viajante searches Google Flights, Google Hotels, and Booking.com. Use it to
compare flights, find cheaper travel dates, explore destinations, or look up
places to stay. It runs on your computer and connects directly to the travel
sites; no API keys are required.

You can run a search from the command line, call the Python library, or connect
an AI assistant through the Model Context Protocol (MCP). Results include
prices, itinerary details, source text, and links where available.

[Usage guide](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md)
· [Contributing](https://github.com/felipebasurto/viajante/blob/main/CONTRIBUTING.md)
· [Report an issue](https://github.com/felipebasurto/viajante/issues)

## Install

Requires **Python 3.10 or later**.

PyPI:

```bash
pip install viajante
```

npx (needs [`uv`](https://docs.astral.sh/uv/) and Python 3.10+ on PATH):

```bash
npx -y -p @viajante/mcp viajante airports JFK
```

No install (same `uv` + Python 3.10+):

```bash
uvx --from viajante viajante airports JFK
```

## Quick start

Search for a one-way flight or a hotel stay:

```bash
viajante flights JFK-LHR:2026-11-15 --fetch sweep
viajante hotels London 2026-11-15 2026-11-20 --currency GBP --source google
```

Use future dates when trying the examples. `JFK` and `LHR` are airport codes;
`viajante airports london` lists airports for a city so you can choose one.

These searches use HTTP and do not need a browser. Booking.com and the browser
mode for Google Flights require the optional
[browser setup](#optional-browser-support).

## Connect an AI assistant

Viajante provides a local MCP server over stdio. Requires
[`uv`](https://docs.astral.sh/uv/getting-started/installation/) and Python 3.10+.
Add this entry to your assistant's MCP configuration:

```json
{
  "mcpServers": {
    "viajante": {
      "command": "npx",
      "args": ["-y", "@viajante/mcp"]
    }
  }
}
```

That entry runs `uvx --from viajante[mcp,browser]==<version> viajante-mcp`, with `<version>` pinned to the npm package. `search_explore` needs the browser extra. Install Chromium once (Playwright's browser cache is shared per user): `uvx --from 'viajante[mcp,browser]==<version>' playwright install chromium`.

Native Python (no Node):

```json
{
  "mcpServers": {
    "viajante": {
      "command": "uvx",
      "args": ["--from", "viajante[mcp]", "viajante-mcp"]
    }
  }
}
```

The native configuration supports Google Flights and Google Hotels without Chromium.
npx still needs `uvx` (and Python 3.10+) on PATH. If you use an existing
Python environment instead, install `pip install 'viajante[mcp]'` and configure
the client to run that environment's `viajante-mcp` executable.

For a client that only connects to a URL, run the server on loopback with
`viajante-mcp --transport streamable-http` and point the client at
`http://127.0.0.1:8000/mcp`. This has no authentication; every client shares
this machine's IP and the provider cooldown, so do not expose it. Details are in
[usage](docs/usage.md#mcp-client-compatibility).

Once connected, you can ask:

> Find a seven-night round trip from BOS to LHR, departing between November 1
> and November 30, 2026. Compare the departure dates.

> Search for hotels in Tokyo from November 12 to November 16, 2026, for two
> adults. Use JPY and require free cancellation.

Every tool result (except `lookup_airports`) carries one envelope: `status`, `completeness`, `empty_reason` (`provider_empty` / `filtered_out` / `not_loaded`), `retry_after` and `observed_at`. Only `provider_empty` means the provider found nothing.

The server exposes twenty-two tools:

| Tool | Use it to |
| --- | --- |
| `search_flights` | Search one-way, round-trip, or multi-city flights. |
| `search_dates` | Compare the cheapest returned fare for each departure date in a window. |
| `search_flex` | Check dates around a target departure, then fetch flights for the cheapest day. |
| `search_explore` | Discover destinations from an origin airport and price a shortlist. |
| `search_hotels` | Find stays with total-stay prices and cancellation details where available. |
| `search_hotel_rooms` | Read Skiplagged room rates for one named hotel. |
| `get_hotel_details` | Read a hotel offer this process returned, with an optional separate room quote. |
| `search_trip` | Search flights and hotels together and sum compatible results. |
| `search_split_tickets` | Opt-in separately ticketed itineraries (a self-transfer via a hub, or mixed one-ways for a round trip) built from real one-way quotes. Connections between tickets are not protected. |
| `recheck_offer` | Re-check an earlier flight offer with one fresh search: same price, price changed, not found, multiple matches, incomplete identity, or check failed (the check could not complete, which never means the offer is gone). |
| `lookup_airports` | Look up airport or metro codes offline. |
| `search_hidden_city` | Opt-in Skiplagged hidden-city fares (not mixed with Google results). |
| `compare_awards` | Cents-per-point math for a named award offer (no seat inventory). |
| `lookup_transfers` | Local points transfer-partner table. |
| `validate_itinerary` | Check a proposed itinerary against the searches' own evidence. |
| `plan_stay_blocks` | Group consecutive nights that have the same people. |
| `split_stay_costs` | Split named stay totals among the people who sleep there. |
| `verify_answer` | Flag amounts, codes, dates, or links in a draft reply that no search returned. |
| `price_history` | Read the prices this machine recorded for a query (opt-in, local, one currency). |
| `watch_price` | Re-run a saved flight or hotel search once and report the change since its last observation. |
| `get_runtime_info` | Read the executing package version offline. |
| `get_guide` | Read the long operational guide (also the `viajante://guide` resource). |

## Use the command line

Each search command accepts `--save FILE` to write a JSON report. Run
`viajante <command> --help` for its options.

| Command | Purpose |
| --- | --- |
| `viajante flights` | Search specific routes and dates. `--split-tickets` opts in to separately ticketed alternatives (not protected if a connection is missed). |
| `viajante dates` | Compare departure dates across a window of up to 31 days. |
| `viajante flex` | Search a few days either side of a target date. |
| `viajante explore` | Find destinations from an origin airport. |
| `viajante hotels` | Search Google Hotels or Booking.com. |
| `viajante trip` | Search flights and a hotel stay in one request. |
| `viajante recheck-offer` | Re-check a saved flight offer against a fresh search; exit 2 means the check could not complete (not a booking guarantee). |
| `viajante airports` | Find airport codes by city or code. |
| `viajante hidden-city` | Opt-in Skiplagged hidden-city search. |
| `viajante awards` | Cents-per-point value of a named award offer. |
| `viajante points` | Points transfer-partner lookup. |
| `viajante history` | Prices this machine recorded for a query (opt-in recording; `--clear` deletes it). |
| `viajante watch` | Re-run a saved flight or hotel query now and report the change. |

For example, compare dates for a seven-night round trip:

```bash
viajante dates BOS-LHR --from 2026-11-01 --to 2026-11-30 --nights 7
```

See the [usage guide](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md)
for round trips, flexible dates, filters, hotel searches, and saved reports.

## Use Python

`get_flights` accepts the same route format as the CLI and returns a typed
report:

```python
from viajante import get_flights

report = get_flights("JFK-LHR:2026-11-15", fetch="sweep", top=5)

for result in report.queries:
    if result.status == "ok":
        for offer in result.offers:
            print(offer.price, report.currency, offer.airline, offer.duration)
    else:
        print(result.error)
```

The library also exports `FlightQuery`, `HotelQuery`, and the `search_*`
functions. The
[Python examples](https://github.com/felipebasurto/viajante/blob/main/docs/usage.md#python-library)
show how to build queries directly.

## Optional browser support

For Booking.com or Google Flights with `--fetch detail`, install Playwright
and Chromium in the environment that runs Viajante:

```bash
pip install 'viajante[browser]'
playwright install chromium
```

For the `uvx` MCP configuration, change `--from` to `viajante[mcp,browser]` and
install Chromium through that same environment:

```bash
uvx --from 'viajante[mcp,browser]' playwright install chromium
```

Flight searches default to `--fetch auto`: with Playwright installed, they use
the browser for one or two queries and HTTP for larger batches. Without
Playwright, they use HTTP. Hotel searches default to Booking.com in the CLI
and Google Hotels in MCP; use `--source google` for CLI hotel searches without
a browser.

## Understanding the results

- **Currency:** Flight searches use the origin airport's country to choose a
  currency when possible. You can set one explicitly with `--currency`.
  Standalone hotel searches require a currency. Viajante does not convert
  between currencies.
- **Baggage:** Use `--bags` or `--carry-on` to request baggage pricing from
  Google Flights. An optional `--baggage-buffer` affects ranking; it is a
  user-supplied amount, not a quoted bag fee, and defaults to zero.
- **Hotels:** Prices cover the requested stay. Free cancellation is required
  by default, but an applied search filter and a property's stated terms are
  recorded separately. Google ratings use a 0–5 scale; Booking.com uses 0–10.
- **Recommendation:** A successful flights query may carry a `recommendation`
  block (none when the provider returned nothing): a pick that respects the requirements you named (and reports any it
  had to relax), plus up to three genuinely different options with factual
  `highlights` and `tradeoffs`. The score weights are published, unknown
  fields are labelled unknown, and prices in different currencies are never
  compared. It adds to the offer list; it does not replace it.
- **Price comparisons:** When present, `typical` is a median from the same
  route's date calendar. It is not a historical market average.
- **Trip totals:** A combined total is shown only when both searches return
  usable prices, their dates overlap, and their currencies match. It adds the
  flight fare and hotel stay; it does not create a package booking.
- **Missing information:** Fields that cannot be determined remain unknown
  or are omitted. Source text is retained with offers to help you inspect
  the result.

Travel sites can change their pages, block requests, or return incomplete
results. Prices and availability can also change after a search. Check the
final fare, baggage allowance, hotel total, and cancellation terms on the
provider's site before booking.

## Contributing

Bug reports, documentation improvements, and code contributions are welcome.
The [contributor guide](https://github.com/felipebasurto/viajante/blob/main/CONTRIBUTING.md)
covers local setup and the offline test suite. For a bug report, include your
version, command, and error message, with personal information removed.

## License

Viajante is available under the
[MIT License](https://github.com/felipebasurto/viajante/blob/main/LICENSE).
It is an independent project and is not affiliated with Google, Booking.com,
or any airline. Use of those services is subject to their respective terms:
[Google](https://policies.google.com/terms) and
[Booking.com](https://www.booking.com/content/terms.html).

<!-- mcp-name: io.github.felipebasurto/viajante -->
