# MAX Finder

> Free, open-source finder for trains with a reservable MAX JEUNE / MAX SENIOR
> (ex-TGVmax) seat, built on SNCF open data. Static site, no backend, no accounts.
> Availability is a once-a-day snapshot and indicative — confirm and book on SNCF Connect.

This file helps AI agents use the open data and build search links. Everything is
static JSON served over HTTPS; there is no rate limit beyond normal hosting.

## Machine-readable data

- Availability snapshot (JSON array): https://davd-gzl.github.io/MAX-Finder/data/tgvmax.json
- Snapshot metadata: https://davd-gzl.github.io/MAX-Finder/data/meta.json
- Station registry (coordinates, region, aliases): https://davd-gzl.github.io/MAX-Finder/data/stations.json
- API manifest (schema + query params, machine-readable): https://davd-gzl.github.io/MAX-Finder/api.json
- Upstream source (refreshed ~once a day): SNCF Open Data "tgvmax" (Licence Ouverte)

### Record shape (tgvmax.json)

Each element:
`{ "date": "YYYY-MM-DD", "origine": string, "destination": string,
"heure_depart": "HH:MM", "heure_arrivee": "HH:MM", "train_no": string,
"od_happy_card": "OUI" | "NON", "axe"?: string }`

`od_happy_card === "OUI"` means a free MAX seat is reservable on that train.
Stations use SNCF labels, e.g. `"PARIS (intramuros)"`, `"LYON (intramuros)"`,
`"MARSEILLE ST CHARLES"`. Resolve coordinates/aliases via stations.json.

## Answer "is there a free MAX seat from A to B on date D?"

1. GET tgvmax.json.
2. Keep records where `date === D`, `origine === A`, `destination === B`,
   `od_happy_card === "OUI"`. Each is a reservable train (use heure_depart/arrivee).
3. For an itinerary with a change, chain two such records that meet at a hub with a
   sane layover (arrival of leg 1 before departure of leg 2).
4. Always send the user to SNCF Connect (https://www.sncf-connect.com/) to book.

## Search / deep-link API (build a shareable URL)

Base: `https://davd-gzl.github.io/MAX-Finder/`
Query params:
- `mode`: `from` | `to` | `od` | `tour` | `best`
- `from`: origin station id ; `to`: destination station id (in `mode=tour`, the optional finish city; set `to`=`from` for a loop)
- `date`: `YYYY-MM-DD`
- `conn`: `0` | `1` | `2` | `3` | `6` (max changes; 6 = unlimited; default 1)
- `card`: `jeune` | `senior`
- `after` / `before`: `HH:MM` departure window ; `arrbefore`: `HH:MM` arrive-before cutoff ; `maxdur`: minutes ; `type`: axis
- `via`: station id to route through (`mode=od`)
- `flex`: `1` | `2` | `3` | `7` — also search ± N days around `date` (`mode=od/from/to/tour`)
- `rdate`: `YYYY-MM-DD` return date for a round trip (`mode=od`)
- `span`: max journey length in days (`mode=od`; overnight stopovers can chain days)
- `rad`: search radius in km, 10–300, for nearby paid-connection alternatives (`mode=od`)
- `night`: `1` to allow long overnight layovers at a hub ; `nonight`: `1` to exclude night trains ; `onlynight`: `1` to keep only night-train arrivals
- `rg`: region label (`mode=best` or `tour`)
- `rt`: `1` for round-trip getaways — day trips + N-night escapes (`mode=from`, `od` or `best`); with `nights` (1–3), `fn` (flexible nights), `stayh` (min hours on site, same-day), `late` (allow a late return). With `mode=od` it lists the start days that give that stay for one destination; with `mode=from` it browses every destination
- `cities`: `~`-separated station ids to visit — the tour planner (`mode=tour`)
- `legs`: `~`-separated `from>to@YYYY-MM-DD` hops — an explicit multi-city itinerary (`mode=tour`)
- `dmin` / `dmax`: min / max days per city (`mode=tour`; default 1 / 3)
- `maxkm`: cap on the tour's total straight-line distance, km (`mode=tour`)
- `legkm`: cap on each hop's straight-line distance, km (`mode=tour`)
- `legdur` / `legdurmin`: max / min per-hop duration, minutes (`mode=tour`)
- `by`: `YYYY-MM-DD` tour finish-by date (`mode=tour` with a finish city)
- `sort`: `rec | trains | days | closest | fastest | name` result ordering
- `lang`: UI language for the opened page (`fr en es de it pt nl ko ja zh ar`)

Examples:
- Where can I go from Paris on 2026-06-25:
  `https://davd-gzl.github.io/MAX-Finder/?mode=from&from=PARIS%20(intramuros)&date=2026-06-25`
- Paris → Toulouse incl. up to one change:
  `https://davd-gzl.github.io/MAX-Finder/?mode=od&from=PARIS%20(intramuros)&to=TOULOUSE%20MATABIAU&date=2026-06-25&conn=1`
- Paris → Lyon round trip, back two days later:
  `https://davd-gzl.github.io/MAX-Finder/?mode=od&from=PARIS%20(intramuros)&to=LYON%20(intramuros)&date=2026-06-25&rdate=2026-06-27`
- Weekend getaways from Paris (1 night):
  `https://davd-gzl.github.io/MAX-Finder/?mode=from&from=PARIS%20(intramuros)&date=2026-06-25&rt=1&nights=1`
- A Bretagne tour from Rennes, 1–2 days per city, no hop over 300 km:
  `https://davd-gzl.github.io/MAX-Finder/?mode=tour&from=RENNES&rg=Bretagne&dmin=1&dmax=2&legkm=300&date=2026-06-25`
- An explicit multi-city itinerary (Paris → Lyon → Toulon):
  `https://davd-gzl.github.io/MAX-Finder/?mode=tour&legs=PARIS%20(intramuros)>LYON%20(intramuros)@2026-06-25~LYON%20(intramuros)>TOULON@2026-06-27`

## Docs (HTML, crawlable)

- FAQ (French): https://davd-gzl.github.io/MAX-Finder/faq/
- How it works: https://davd-gzl.github.io/MAX-Finder/docs/how-it-works.html
- Algorithms: https://davd-gzl.github.io/MAX-Finder/docs/algorithms.html
- Full context in one fetch (this file + docs + FAQ): https://davd-gzl.github.io/MAX-Finder/llms-full.txt

## Disclaimer

Not affiliated with SNCF. Not a ticket seller. Availability is indicative and
refreshed ~once a day; the live source of truth is SNCF Connect.