# NS travel information

Live departures, delays and disruptions on the Dutch railways. Free, with a key from the NS API portal.

- Publisher: Nederlandse Spoorwegen
- Area: Netherlands · Finest detail: station and trip
- Period: heden · Refreshed: every minute
- Access: Free key · Licence: Voorwaarden NS
- Join keys: stationscode
- Status: grijs
- URL: https://apiportal.ns.nl

## What can you do with it?
- **How often is your train late?.** Store departures from one station for a month and count delays.

## Interesting combinations
- More disruptions in heat or storms? → [knmi-daggegevens](https://www.opendataindex.nl/en/bron/knmi-daggegevens.md) via datum. Join daily disruptions with maximum temperature and gusts.

## Similar sources
- [Rijden de Treinen](https://www.rijdendetreinen.nl/open-data): Historical disruptions and delays as open data.

## API (OpenAPI 3.0.1)

- Base: https://gateway.apiportal.ns.nl/reisinformatie-api
- Access: Free key required, sent in the header Ocp-Apim-Subscription-Key. Without a key: HTTP 401 (tested). Open Data Index keeps its key on the server. (tested)
- Formats: JSON
- Filtering: No general filter language: each endpoint has its own query parameters (see below).; 

### Endpoints
- `GET /api/v3/trips`: Trips
- `GET /api/v3/trips/trip`: Single trip
- `GET /api/v3/trips/booked-trip`: Booked trip
- `GET /api/v3/price`: Domestic prices (deprecated)
- `GET /api/v3/disruptions`: Disruptions (deprecated)
- `GET /api/v3/disruptions/{type}/{id}`: Single disruption (deprecated)
- `GET /api/v3/disruptions/station/{stationCode}`: Station disruptions (deprecated)
- `GET /api/v2/stations`: Stations (deprecated)
- `GET /api/v2/stations/nearest`: Get stations closest to provided coordinates (deprecated)
- `GET /api/v2/price`: Domestic prices
- `GET /api/v2/journey`: Journey details
- `GET /api/v2/departures`: Departures (deprecated)
- `GET /api/v2/arrivals`: Arrivals (deprecated)
- `GET /api/v1/calamities`: Calamities (deprecated)
- `GET /api/openapi`: OpenAPI Spec

### Parameters
- `dateTime`: Datetime that the user want to depart from his origin or or arrive at his destination · on 4 endpoints (from the description)
- `travelClass`: Class of travel to use when calculating product prices · on 4 endpoints (from the description)
- `lang`: Language to use for localizing the travel advice. Only a small subset of text is translated, mainly notes. Defaults to Dutch · on 3 endpoints (from the description)
- `fromStation`: NS station code of the origin station · on 3 endpoints (from the description)
- `toStation`: NS station code of the destination station · on 3 endpoints (from the description)
- `nsr`: NSR number for the customer making this request. Since the replacement of the NSRA backend in Reisinfo with PAS, we do not use the NSR … · on 2 endpoints (from the description)
- `accessibilityEquipment1`: Accessibility equipment to use when searching for trip assistance options (AVG/PAS) · on 2 endpoints (from the description)
- `accessibilityEquipment2`: Accessibility equipment to use when searching for trip assistance options (AVG/PAS) · on 2 endpoints (from the description)
- `product`: Name of the product that will be used in travel · on 2 endpoints (from the description)
- `discount`: Discount of travel to use when calculating product prices · on 2 endpoints (from the description)
- `travelRequestType`: directionsOnly only plans a google directions (walk/bike/car) advice · on 2 endpoints (from the description)
- `ctxRecon`: Reconstruction context to use as basis for finding trip. Can be found in the /api/v3/trips output · on 2 endpoints (from the description)
- `travelType`: Return the price for a single or return trip. Defaults to single · on 2 endpoints (from the description)
- `isJointJourney`: Set to true to return the price including joint journey discount · on 2 endpoints (from the description)
- `adults`: Number of adults to return the price for. Defaults to 1 · on 2 endpoints (from the description)
- `children`: Number of children to return the price for. Defaults to 0 · on 2 endpoints (from the description)
- `routeId`: Specific identifier for the route to take between the two stations. This routeId is returned in the /api/v3/trips call. · on 2 endpoints (from the description)
- `plannedArrivalTime`: Planned arrival time of the trip. Is used to find the correct route, if multiple routes are possible between the origin and destination … · on 2 endpoints (from the description)
- `limit`: The limit is only applied when call is performed with q parameter. If invoked by countrycodes only, no limit is applied · on 2 endpoints (from the description)
- `station`: NS Station code for the station to return departures for. Can be left empty if uicCode parameter is provided. · on 2 endpoints (from the description)
- `uicCode`: UIC code for the station to return departures for. Can be left empty if station parameter is provided. · on 2 endpoints (from the description)
- `maxJourneys`: Number of departures or departures to return. Defaults to 40 · on 2 endpoints (from the description)
- `originUicCode`: UIC code of the origin station · on v3/trips (from the description)
- `originLat`: Latitude of the origin location. Should be used together with originLng. If the origin is a station, just provide the uicCode instead of … · on v3/trips (from the description)
- `originLng`: Longitude of the origin location. Should be used together with originLat. If the origin is a station, just provide the uicCode instead of … · on v3/trips (from the description)
- `originName`: Name of the origin location. Will be returned in the response · on v3/trips (from the description)
- `destinationUicCode`: UIC code of the destination station · on v3/trips (from the description)
- `destinationLat`: Latitude of the destination location. Should be used together with destinationLng. If the destination is a station, just provide the … · on v3/trips (from the description)
- `destinationLng`: Longitude of the destination location. Should be used together with destinationLat. If the destination is a station, just provide the … · on v3/trips (from the description)
- `destinationName`: Name of the destination location. Will be returned in the response · on v3/trips (from the description)

### Limits and pitfalls
- The description lists https://apigateway.ns.nl/reisinformatie-api as server, but the working gateway is https://gateway.apiportal.ns.nl/reisinformatie-api. (tested)
- 300 requests per 5 minutes for non-paying users; above that HTTP 429 with a Retry-After header. (from the description)
- NS terms forbid the NS logo in your application and altering data so that it becomes incorrect. (from the description)
- Responses are compressed (gzip); use curl --compressed or a client that decompresses. (tested)
- Arrivals and departures in this API are deprecated: NS points to https://gateway.apiportal.ns.nl/timetable-api/v2/. (from the description)
- The NS portal shows API definitions only after login; only the Reisinformatie API spec can be fetched through the gateway. (tested)

### Example
```
https://gateway.apiportal.ns.nl/reisinformatie-api/api/v2/departures?station=UT&maxJourneys=2
```