Ns International
Plan train trips on NS and NS International via the official NS Reisinformatie API (apiportal.ns.nl) — the only public, supported NS interface. Covers PLANNING only: journey advice, prices, live departures and disruptions, for domestic NL trains and the international connections NS International sells (Belgium, Germany, France; Eurostar, Eurocity, ICE).
There is NO public booking/payment API for NS or NS International, so this
model does not purchase tickets. Each planned option carries a bookingUrl
deep-link into the NS / NS International site where the traveller completes
the booking with their own account and payment method.
Model @magistr/ns-international:
stations— fetch and cache the station directory as astation-indexresource for name→code/UIC resolution; withquery, print matches.plan— journey advice between two stations (name, NS code, or UIC). Returns ranked options with times, transfers, per-leg train/operator, crowding, the cheapest fare found, and a bookingUrl. SupportsdateTime(ISO-8601; empty = now) andsearchForArrival(arrive-by vs depart-at). International (cross-border) fares are often unavailable from this API and surface as "price n/a"; times and routing are complete.disruptions— active disruptions and maintenance, with optionalisActive/typefilters.
Auth: a free "Reisinformatie API" subscription key from apiportal.ns.nl,
sent as the Ocp-Apim-Subscription-Key header. Supply it through
globalArguments.apiKey via a ${{ vault.get(<vault>, NS_API_KEY) }}
expression — never a literal.
2026.10.25.10
- Repo-wide republish; no functional change.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| apiKey | string | NS Reisinformatie API subscription key (Ocp-Apim-Subscription-Key). |
| baseUrl? | string | Reisinformatie API base URL. |
| userAgent? | string | User-Agent header. |
| Argument | Type | Description |
|---|---|---|
| query? | string | Case-insensitive substring to list matching stations. |
| Argument | Type | Description |
|---|---|---|
| from | string | Origin: station name, code, or UIC. |
| to | string | Destination: station name, code, or UIC. |
| dateTime? | string | ISO-8601 departure (or arrival) time. Defaults to now. |
| searchForArrival? | boolean | Treat dateTime as the desired ARRIVAL time instead of departure. |
| travelClass? | number | 1 or 2 (travel class). Omit for the API default. |
| Argument | Type | Description |
|---|---|---|
| isActive? | boolean | Only currently active disruptions. |
| type? | string | Filter by disruption type (DISRUPTION, MAINTENANCE, CALAMITY). |
Resources
2026.10.15.9
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.19.1
First release.
stationsfetches the NS station directory and caches it asstation-index; withqueryit lists matching stations by name or code.planresolvesfrom/to(name, NS code or UIC) and returns ranked journey options with per-leg train, operator, crowding, the cheapest fare found and abookingUrl(ns.nl for domestic, NS International for cross-border). Planning only: NS has no public booking API.disruptionslists active disruptions and maintenance, withisActiveandtypefilters.
Fixed before release
disruptionswrote its snapshot under the data namelatest, which swamp reserves; every real run would fail. It now writescurrent.- A trailing slash on
baseUrlproduced//v3/trips; the base is now normalised. - Malformed responses (a JSON
nullbody, non-arraytrips/fares,nulltrips, legs or disruptions) crashed the methods; they are now skipped. planrejects a non-ISO-8601dateTimeand atravelClassother than 1 or 2 before sending a request, and a blank station name no longer reports a misleading "ambiguous" match.- An empty
apiKeyis rejected before any request is sent.
Tests
- Hand-authored contract fixtures and the five quality suites (contract,
methods, adversarial, coverage, property), all with
fetchstubbed.
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Docs keep secrets in a vault1/1earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License2/2earned
- Verified public repository2/2earned