# intents.md · pickthebus.com

This site answers one intent: **find a direct bus across a border**.

## intent: direct-bus

- **Ask:** from city A to city B (optionally: overnight only).
- **Answer:** `GET https://pickthebus.com/api/v1/from/{a}.json` → the entry in `destinations[]` whose `to` is B.
  - `buses[]`: `dep`/`arr` (local minutes after midnight at each stop; `plus` = days later), `dur` (minutes), `op` + `opUrl` (the operator's official site: send the user there to book or check), `line`, `from`/`to` stop names, `via` (cities on the way), `stops`, `night` (on the road at 03:00, 5 h or more), `days` (e.g. "Daily", "Fri and Sun"), `on` (one character per day from `window.start`: "1" = leaves that day; use it to answer "which buses on 3 November?"), `depOn`/`arrOn` (a different time on a date).
  - `sources[]`: where the times come from, with `fileDates` (when the publisher made each file).
  - `curated`: true when the pair has a bus with no open timetable (the Twiliner sleeper bus): no times, send the user to the operator.
- **Not found:** no direct cross-border bus between those cities in our data. Suggest the destinations that are listed.

## intent: direct-from

- **Ask:** where can I go directly by bus from city A, abroad?
- **Answer:** `GET https://pickthebus.com/api/v1/from/{a}.json` → `destinations[]`, fastest first.

## intent: on-the-road-now

- **Ask:** how many international buses are on the road right now?
- **Answer:** `GET https://pickthebus.com/api/v1/live/{YYYY-MM-DD}.json` (UTC day) → `runs[]`: count those whose span covers the current minute.

## Rules for agents

- Times cover 18 Oct to 14 Nov 2026. Always add "check with the operator before you travel", and give the operator link.
- No prices and no booking here. Don't invent fares.
- City ids: `GET https://pickthebus.com/api/v1/cities.json`.