# GlobeHops

> GlobeHops visualises air journeys as great-circle routes on an interactive 3D globe, with shared distance, flight-time, layover, local-time and daylight calculations. Free, static, no account or API key.

This guide lives at the site root, `https://globehops.marki.im/llms.txt`. GlobeHops moved here from `https://tmrk.github.io/globehops/`; old links still redirect, but build new ones on `https://globehops.marki.im/`. These discovery files describe GlobeHops's own contract; they do not claim conformance to a formal agent standard.

## Turn a booking into a link

Asked to show a flight booking, confirmation email, PDF, screenshot or pasted itinerary in GlobeHops? Reply with one readable link and nothing else:

1. Stops in travel order as IATA codes joined by `-`: `route=BUD-FRA-JFK`. A change of plane on the way (a connection) stays in the same route.
2. Times exactly as printed, airport-local, `YYYY-MM-DDTHH:MM`: `depN`/`arrN` are the departure from and arrival at the Nth stop of that route (1-based). Include every departure and arrival given; never convert time zones; omit times you don't have.
3. Time spent at a destination (anything that isn't a connection) ends the journey. The return or next journey is a new section with its own stop numbers: `2.route`, `2.dep1`, `2.arr2`, … then `3.*` up to `6.*`.
4. Several offers, or several people's trips, to show together: the 2nd uses `b.route`, `b.dep1`, …, the 3rd `c.*`, the 4th `d.*`; an alternative's return is `b.2.route`, `b.2.dep1`, …. Name each with `label` (URL-encoded, 1–40 characters): the traveller's name for people's trips (`label=Anna&b.label=Ben`), else the airline or offer (`label=Lufthansa&b.label=Nonstop`). Names appear on the tabs, table, timeline and planes.
5. Use only these readable parameters (not `itinerary=`) and return the full URL starting `https://globehops.marki.im/?`.

Example – out via Frankfurt on 1 December, back nonstop on 10 December:
https://globehops.marki.im/?route=BUD-FRA-JFK&dep1=2026-12-01T07:10&arr2=2026-12-01T08:40&dep2=2026-12-01T10:10&arr3=2026-12-01T13:05&2.route=JFK-BUD&2.dep1=2026-12-10T18:00&2.arr2=2026-12-11T08:15

Example – Anna from London and Ben from New York meet in Tokyo and fly home a week later:
https://globehops.marki.im/?route=LHR-HND&dep1=2026-12-01T11:00&label=Anna&2.route=HND-LHR&2.dep1=2026-12-08T11:30&b.route=JFK-HND&b.dep1=2026-12-01T12:00&b.label=Ben&b.2.route=HND-JFK&b.2.dep1=2026-12-08T17:00

## Build a link

- [Simple CPH–JFK](https://globehops.marki.im/?route=CPH-JFK): airport codes separated by hyphens.
- [Three-hour Heathrow connection](https://globehops.marki.im/?route=CPH-LHR_180-JFK): custom transfer minutes follow `_`; default is 90 minutes.
- [Scheduled departure](https://globehops.marki.im/?route=CPH-LHR-JFK&dep1=2026-11-20T08:15): depN/arrN are airport-local times at 1-based stop N. Omitted times are estimated when anchored by an entered time.
- [Worked examples](https://globehops.marki.im/agent/examples.json): complete readable and alternative `?itinerary=<base64url UTF-8 JSON>` URLs. The itinerary parameter overrides readable parameters.

View parameters: `t` is an ISO instant, `play=1` starts playback (respecting reduced motion), `live=1` follows the real current time, `speed=auto|1800|3600|7200`, `clock=local|utc|<airport code in any journey>`, `units=km|mi`, `daynight=0` disables shading, `follow=1` enables the aircraft camera (off by default; user camera input exits).

Language: use `/en/`, `/hu/` or `/sv/`; `?lang=en|hu|sv` is an alias on the unprefixed path. An explicit locale path wins. Document `view.lang` and MCP `view.lang` generate locale paths. `names=1` enables place-name labels, `borders=0` hides country borders; either accepts 0/1. `leg=N` selects and frames a one-based flight without seeking time. When combined, follow camera takes priority over flight framing. Link view overrides apply to this visit and do not change stored user preferences.

## Compare journeys

Compare 2–4 alternatives on one UTC clock: offers for one traveller, or different people's journeys. Journey A keeps ordinary keys; B–D use `b.route`/`b.depN`/`b.arrN`/`b.label`, then `c.*` and `d.*`. Optional labels (1–40 characters without controls) name each alternative, e.g. the traveller or the airline, on its tab, table row, timeline lane and plane; a single journey's `label` becomes its title. People can rename journeys in the app (Edit → Name), which updates the same parameters. Encode spaces, Unicode, `&` and `=`; keys are case-insensitive. `leg` refers to A. Older clients show A.

Readable example: `https://globehops.marki.im/?route=BUD-LHR-JFK&dep1=2026-12-01T07:10&label=Via%20London&b.route=BUD-JFK&b.label=Direct`.

Document example: `{"version":1,"journeys":[{"label":"Direct","stops":[{"airport":"BUD"},{"airport":"JFK"}]},{"stops":[{"airport":"BUD"},{"airport":"LHR"},{"airport":"JFK"}]}]}`. Encode as the existing `?itinerary=` parameter. Exactly one of stops/journeys/sections is allowed; document journeys accept 1–4 items.

MCP `compare_journeys` example: `{"journeys":[{"label":"Direct","route":"BUD-JFK"},{"route":"BUD-LHR-JFK"}],"assumeDeparture":"2026-12-01T07:00Z","view":{"play":true}}`. Each alternative supplies exactly one of route/stops/sections; route plus returnRoute and optional stay is a round-trip shorthand. The result includes both URLs, humanSummary, journey details and comparison (fastest, firstArrival, duration ranking/deltas). Entered airport-local times remain absolute; undated journeys align to the earliest dated departure or assumeDeparture. Ties have no winner; invalid journeys are excluded.

`visualize_route` and `validate_itinerary` accept journeys documents; visualization adds comparison and A's summary totals. Multi-journey calculation/timeline requests direct agents to compare_journeys. Browser parsing accepts compare_journeys without assumeDeparture and set_route with journeys documents; App/rendering integration is tracked in [the comparison model](https://github.com/tmrk/globehops/blob/main/docs/ROUTE_COMPARISON.md).

## Round trips and multi-stage trips

A trip is a sequence of journeys separated by explicit stays (never layovers). Compare 2–4 trips by giving each alternative the same 1–6 sections. The first section uses ordinary keys; later ones use `2.route`/`2.depN`/`2.arrN`/`2.label`/`2.stay` through `6.*`. Example: `https://globehops.marki.im/?route=CPH-AMS-NBO&dep1=2026-11-15T07:00&2.route=NBO-CDG-CPH&2.dep1=2026-11-20T23:55`. `N.stay` (`5d`, `36h`, `90m`) places a section without times after the previous one (default 7 days, marked estimated/assumed). Documents use `{"version":1,"sections":[{"stops":[…]},{"label":"Home","stayMinutes":7200,"stops":[…]}]}` (1–6 sections). `calculate_route` returns `kind:"trip"`, sections, stays (minutes, calendar days, source, provenance) and trip totals; timelines add a `stay` phase. `leg` counts flights across the trip.

Compared round trips use A's `route` and `2.route`, then B's `b.route` and `b.2.route` (through `d.6.*`). Example: `https://globehops.marki.im/?route=BUD-FRA-JFK&2.route=JFK-FRA-BUD&b.route=BUD-JFK&b.2.route=JFK-BUD`. `leg` counts A's flights across its sections; `clock` may name any alternative's section airport. Links tolerate different section counts; documents require equal counts and each journey item contains exactly one of stops or sections (all items use the same form).

Document example: `{"version":1,"journeys":[{"label":"Via Frankfurt","sections":[{"stops":[{"airport":"BUD"},{"airport":"FRA"},{"airport":"JFK"}]},{"stops":[{"airport":"JFK"},{"airport":"FRA"},{"airport":"BUD"}]}]},{"label":"Nonstop","sections":[{"stops":[{"airport":"BUD"},{"airport":"JFK"}]},{"stops":[{"airport":"JFK"},{"airport":"BUD"}]}]}]}`.

MCP example: `{"journeys":[{"route":"BUD-FRA-JFK","returnRoute":"JFK-FRA-BUD","stay":"5d"},{"sections":[{"route":"BUD-JFK"},{"route":"JFK-BUD","stay":7200}]}],"assumeDeparture":"2026-12-01T07:00Z"}`. A section supplies exactly one of route/stops, optional label and a stay before later sections (integer minutes or `5d`/`36h`/`90m`). Compared-trip results have `kind:"trip_comparison"`, journeys with sections/stays/trip totals plus travelMinutes, and comparison.fastest, travelMinutes ranking/deltas, and per-section winners/deltas. Ranking excludes stays and incomplete trips. An untimed trip aligns section by section with the earliest timed counterpart unless the traveller chose the stay. Plain comparisons add `kind:"comparison"`. Timeline tools remain for single journeys/trips.

## Routing

Generated results use great circles unless a call requests `routing: {"avoidAirspace": true, "diversion": true}` (or `diversion` as 60–370 minutes; default 180 min at 400 kt on one engine). Legs then report `distanceKm` (used for estimates), `greatCircleKm`, `distanceModel` and `route.airspace`/`route.diversion` (`covered`, `adjusted` or `gap`, with the longest modelled diversion time). Diversion coverage is modelled reach of potential diversion airports from runway data, not an ETOPS authorisation or an airline's route. Links can set `airspace=0|1` and `diversion=0|1` for a visit.

## Contract and limits

- [Capabilities](https://globehops.marki.im/agent/capabilities.json): parameters, limits, issue vocabulary and estimation model.
- [Itinerary v1 schema](https://globehops.marki.im/agent/itinerary.schema.json): exactly one of stops (1–10), journeys (1–4 labelled alternatives, each stops or equal-count sections) or sections (1–6 trip journeys with optional stays); transfer-only integer layovers 0–10080 minutes. No unknown properties except a top-level string `$schema`.
- [External agent integration](https://github.com/tmrk/globehops/blob/main/docs/AGENT_INTEGRATION.md): link construction, validation and local MCP setup.

Use IATA, ICAO, alphanumeric OurAirports ident or numeric airport id strings; unknown codes are reported and skipped. Hyphenated idents require numeric IDs in readable links. Maximum URL: 8000 characters; itinerary parameter: 6000 characters. Supported calendar years: 1900–2100.

Local times: `YYYY-MM-DDTHH:MM`, optional `:00` seconds and `±HH:MM` or `Z`. Offsets must match the airport zone at that local wall time. `Z` means a local UTC+0 offset; it does not convert another zone's wall time. Repeated DST hours warn and choose the earlier instant unless disambiguated; nonexistent times error. Absolute instants (`t`, timeline queries) require `Z` or an offset. Date-only readable links are incomplete; document times require hours and minutes.

## Estimates and provenance

Flight estimates use 850 km/h plus 30 minutes, rounded to five minutes. Distances sum great-circle arcs on a sphere of radius 6371.0088 km, along custom vertices when supplied, otherwise directly between airports unless routing is requested. Winds, oceanic tracks, airways, airline timetables and aircraft types are not modelled. Generated aircraft positions and altitudes are illustrative; custom paths use supplied geometry, usable altitudes and recorded times. There is no live tracking. Entered and estimated times are labelled. Undated comparisons align to the earliest dated departure, else an explicit assumed departure; without either they have totals but no timeline. Time-zone rules come from runtime Intl and may change for future dates.

- [Dataset freshness](https://globehops.marki.im/agent/dataset.json): build date, upstream airport commit, counts and time-zone release metadata.
- [Data sources](https://github.com/tmrk/globehops/blob/main/docs/DATA_SOURCES.md): OurAirports public domain, timezone-boundary-builder/OSM ODbL-1.0, NASA imagery and Natural Earth borders.
- [Licence notices](https://github.com/tmrk/globehops/blob/main/THIRD_PARTY_NOTICES.md): code is MIT; data retains its own terms.

## Local MCP server

- [Server source](https://github.com/tmrk/globehops/blob/main/mcp/server.ts): local stdio; clone the repository, run `npm ci` with Node 22.18+, then `node /absolute/path/to/globehops/mcp/server.ts` (or `npm run mcp` in the checkout).
- [MCP configuration and tool examples](https://github.com/tmrk/globehops/blob/main/docs/AGENT_INTEGRATION.md): search_airports, compare_journeys, calculate_route, validate_itinerary, visualize_route, import_route, get_journey_timeline.

Set `GLOBEHOPS_BASE_URL` to override generated links. There is no remote MCP endpoint: the site is static files on Cloudflare Pages. Tools reuse the same calculations as the browser and require no network services.

MCP also exposes resources `globehops://agent/capabilities.json`, `globehops://agent/itinerary.schema.json`, `globehops://agent/examples.json`, `globehops://agent/usage` and the `plan_and_visualize` prompt (`journey` string). `visualize_route` returns readable `url`, complete `itineraryParamUrl`, one-line `humanSummary` and the structured `summary`.

## Experimental browser tools (WebMCP)

When the browser offers model-context tools, the live page registers `import_route` (flight-file text or aviation route string; optional fileName, format, mode replace/compare), `get_journey` (stops, legs, totals, times, issues, current view/link), `set_route` (exactly one route string or v1 itinerary), `compare_journeys` (2–4 alternatives), `set_view` (partial t/play/speed/follow/dayNight/names/borders/airspace/diversion/units/clock/lang/leg), `select_flight` (one-based leg or null for overview), and `get_share_link` (open timeline instant/play state and locale; a live globe stays live). `t` is an ISO instant here; documents use `view.time`. No data is sent anywhere. Invalid arguments return actionable errors without partial changes. Explicit browser-tool playback acts like pressing Play; link autoplay respects reduced motion. No supported API means no registration and no change to normal UI behaviour.

Supports the current draft `document.modelContext.registerTool` with AbortSignal cleanup and legacy `navigator.modelContext` registerTool/unregisterTool or provideContext. This experimental API may change. DOM agents can use accessible airport comboboxes, named flight buttons and timeline controls; names follow the selected language. See the integration guide for exact arguments and lifecycle details.

Custom paths: add track to the departing document stop (never the last). Supply exactly one of points (2–20000 tuples [lat,lng,altitudeMetres|null,ISO-time|null], last two optional) or encoded (trkN codec), with optional kind planned/recorded, format and name (1–80 characters, no controls). Default kind: recorded with two times, otherwise planned. Recorded times fill missing stop endpoints; explicit stop times win and scale playback. Known track altitudes replace illustrative estimates. Explicit paths apply regardless of routing.
Readable links: trkN is the path departing stop N; prefixes compose (b.trk1, 2.trk1, b.2.trk1). Invalid tracks are ignored with an issue. Large share paths are simplified within the 8000-character URL limit, with track_simplified warnings; later tracks may be omitted if endpoints cannot fit. Session calculations remain exact. Oversized itinerary-document links fall back to readable URLs. Link positions round to 1e-5 degrees, altitudes to metres and times to seconds; source/waypoint names are omitted. Tracks travel only in the link or local document; nothing is uploaded. Recipients can read them. MCP/WebMCP import_route parses files and route strings into planned/recorded tracks. Flight results report path kind, distanceKm, greatCircleKm, points, source and recordedDurationMin when applicable. See the custom-path worked examples in agent/examples.json.

## Import a file or a flight plan

Use `import_route` with file contents in `text`, optional `fileName` for detection and `format` to override it. Supported: GPX, KML/KMZ, GeoJSON, CSV/TSV, IGC, Garmin FPL, MSFS/Little Navmap PLN and aviation route strings. Local MCP accepts exactly one of `text` or `base64` (standard padded Base64 KMZ bytes), at most 20 MiB. It returns format/name, flights (matched airport codes, path kind, point count, distances and recorded duration), warnings, an itinerary document, `url`, `itineraryParamUrl`, `humanSummary` and `summary` including link simplification issues. MCP itinerary documents support up to 20,000 points per flight. Optional `view` and `routing` match visualize_route; `compareWithGenerated: true` compares a single imported journey (A) against GlobeHops' generated route (B).

Example tool arguments: `{"text":"EGLL CPT DCT KJFK","format":"route","compareWithGenerated":true}`. Radio aids resolve from the local navaid dataset; unknown fixes and airway/procedure approximations produce warnings. Connecting flights share a journey; an open jaw starts a trip section. Up to 9 flights per journey and 6 sections are retained, with overflow warnings. Errors report a code and message: unrecognised, invalid, no_path, too_large, unsupported or empty.

In the live browser use `{"text":"EGLL CPT DCT KJFK","mode":"replace"}`. `mode: "compare"` adds one imported journey beside an existing journey when there is room; invalid input leaves the plan unchanged. Binary KMZ is supported through local MCP. Parsing stays on the device, nothing is uploaded. Share links simplify long paths to fit the URL budget; recipients can read their positions, altitudes and times. See the integration guide for a GPX example.