Skip to main content

Ns International

@magistr/ns-internationalv2026.10.25.10· MIT· 27d agoBEHAVIORS
01README

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 a station-index resource for name→code/UIC resolution; with query, 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. Supports dateTime (ISO-8601; empty = now) and searchForArrival (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 optional isActive / type filters.

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.

02Release Notes

2026.10.25.10

  • Repo-wide republish; no functional change.
03Behaviors1
@magistr/ns-internationalv2026.10.25.10extensions/models/ns_international.ts

Global Arguments

ArgumentTypeDescription
apiKeystringNS Reisinformatie API subscription key (Ocp-Apim-Subscription-Key).
baseUrl?stringReisinformatie API base URL.
userAgent?stringUser-Agent header.
fn stations(query?: string)
Fetch the NS station directory and cache it as `station-index` for
ArgumentTypeDescription
query?stringCase-insensitive substring to list matching stations.
fn plan(from: string, to: string, dateTime?: string, searchForArrival?: boolean, travelClass?: number)
Plan trips between two stations. `from`/`to` accept a station name,
ArgumentTypeDescription
fromstringOrigin: station name, code, or UIC.
tostringDestination: station name, code, or UIC.
dateTime?stringISO-8601 departure (or arrival) time. Defaults to now.
searchForArrival?booleanTreat dateTime as the desired ARRIVAL time instead of departure.
travelClass?number1 or 2 (travel class). Omit for the API default.
fn disruptions(isActive?: boolean, type?: string)
Fetch active disruptions and maintenance works. Optional `isActive`
ArgumentTypeDescription
isActive?booleanOnly currently active disruptions.
type?stringFilter by disruption type (DISRUPTION, MAINTENANCE, CALAMITY).

Resources

station-index(infinite)— Cached station directory (code/UIC/name/country) for name resolution
trip-plan(infinite)— One journey-planning search result set
disruptions(infinite)— Snapshot of active disruptions / maintenance
04Previous Versions9
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.19.1MIT

2026.09.19.1

First release.

  • stations fetches the NS station directory and caches it as station-index; with query it lists matching stations by name or code.
  • plan resolves from/to (name, NS code or UIC) and returns ranked journey options with per-leg train, operator, crowding, the cheapest fare found and a bookingUrl (ns.nl for domestic, NS International for cross-border). Planning only: NS has no public booking API.
  • disruptions lists active disruptions and maintenance, with isActive and type filters.

Fixed before release

  • disruptions wrote its snapshot under the data name latest, which swamp reserves; every real run would fail. It now writes current.
  • A trailing slash on baseUrl produced //v3/trips; the base is now normalised.
  • Malformed responses (a JSON null body, non-array trips/fares, null trips, legs or disruptions) crashed the methods; they are now skipped.
  • plan rejects a non-ISO-8601 dateTime and a travelClass other than 1 or 2 before sending a request, and a blank station name no longer reports a misleading "ambiguous" match.
  • An empty apiKey is rejected before any request is sent.

Tests

  • Hand-authored contract fixtures and the five quality suites (contract, methods, adversarial, coverage, property), all with fetch stubbed.
05Stats
A
100 / 100
Downloads
21
Archive size
14.0 KB
  • 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
06Platforms
07Labels