Internal API
NRSDB API Documentation
Base URL
https://nrsdb.uk/api/v1
Authentication
Registered users of the API will be issued with a key - all requests (other than this help URL) must pass this key as a Bearer token
Sample Code
const params = new URLSearchParams();
params.append('property', value);
const response = await fetch(`${url}?${params}`, {
'credentials': 'same-origin',
'headers': {
'Authorization': `Bearer ${token}`
'Accept': 'application/json',
'Content-Type': 'application/json',
'X-Requested-With': 'XMLHttpRequest'
},
'method': 'GET'
});
const response = await fetch(url, {
'body': formData,
'credentials': 'same-origin',
'headers': {
'Authorization': `Bearer ${token}`
},
'method': 'POST'
});
NOTE: in my experience it is best not to set the 'Content-Type' header
Endpoints
Routes
/routes - return all Routes
/route/{routeId} - detail of a specific route
Delivery Units
/dus - return all Delivery Units
/dus/route/{routeId} - return Delivery Units on a given route
/du/1 - get details for a specific DU
Sample Return
{
"data": {
"id": 1,
"name": "Ipswich",
"routeId": 2,
"active": true
}
}
ELRs
/elrs - returns all of the ELRs known to the system
/elr/{elrId} - returns the details for a specific ELR
Locations
/locations/{elrId}
Returns the significant locations along a given ELR, with Miles + Yards location and a GeoJSON marker if available
NOTE: data set is too large to return for the entire railway
NOTE: this is different to the Autumn Inspection locations (see below)
Autumn Inspections
/autumn/locations/{routeId} - return all Locations to be inspected on the given route
/autumn/inspections - returns all of the inspections
/autumn/inspections/route/{routeId} - returns all inspections for a given route
Inspection Example Data
{
"id": 33,
"inspectionDate": "2025-06-09T23:55:39+01:00",
"locationId": 236,
"location": {
"id": 236,
"location": "Falconwood",
"locationClass": "Platform",
"routeId": 8,
"ownerId": 33,
"elrId": 81,
"trackId": 1100,
"track": "",
"start": 827,
"end": 827,
"frequency": 1,
"active": true,
"inspections": []
},
"inspectorId": 3,
"inspector": null,
"weather": {
"precipitation": 3,
"wind": 2,
"overhead": 2,
"ground": 2
},
"rail_condition": "dry",
"evaluation": 0,
"action_taken": "",
"comments": "",
"images": []
},
ESRs
/esrs - returns all known ESRs
/esrs/route/{routeId} - returns ESRs for a given route
NOTE: check this!
ESR Data Structure
- refnum (string) - this is made up of a route specific prefix, a three digit incremental counter, plus the two digit year
- original_refnum (string) - this gives the original reference, allowing consumer to apply updates
- routename (string) - long name for the Route
- deliveryunit (string) - responsibly Delivery Unit
- elrcode (string) - ELR of track segment impacted e.g. LTN1
- elrdescription (string) - full description of the ELR e.g. "LIVERPOOL STREET - TROWSE LOWER JN"
- lorId (int) - internal ID of the LOR - use r=lor?lorId=X to convert
- location (string) - description of where the restriction is applied
- reason (string) - describes reason the ESR is imposed
- speed (string) - "Freight Speed / Passenger Speed" - single number if both are same
- withdrawn (bool) - 0 = active, 1 = withdrawn
- whenimposed (string) - W3C format date time string
- etc (null|string) - if set this is a W3C format date time string
- whenwithdrawn (null|string) - if withdrawn === 1, W3C format date time string
- line (array) - details of the Primary Line
- elrId - internal ID, not useful - Primary Line is always on the ELR as given above
- trackId (int) - e.g. 1100 = Up Main
- direction (string) - "Up Direction" | "Down Direction" (yuk)
- linedescription (string) - can be driven by trackId or overridden by Controller
- routeheader (string) - "Primary Line" | "Additional Line"
- speed (string) - repeat for backward compatibility
- boards (array)
- type (string) - short name (no spaces)
- description (string) - long name
- elrId (int) - copied from line
- trackId (int) - copied from line
- miles (int) -
- chains (int) - 0 >= X < 80
- serialNumber (string) - not currently used
Example
{
"refnum": "AICC 008A.22",
"original_refnum": "AICC 008.22",
"routename": "Anglia",
"deliveryunit": "Ipswich",
"elr": 255,
"elrcode": "COC",
"elrdescription": "Colchester to Clacton",
"lorId": 1
"location": "Between here and there",
"reason": "Track - Cyclic Top",
"speed": "30/60",
"withdrawn": 0,
"whenimposed": "2022-09-02 13:53:09",
"etr": null,
"whenwithdrawn": null,
"line": {
"elrId": 255,
"trackId": 1100,
"direction": "Up Direction",
"linedescription": "Up Main",
"routeheader": "Primary Line",
"boards": [
{
"type": "commencement",
"description": "Commencement Board",
"elrId": 255,
"trackId": 1100,
"miles": 1,
"chains": 42,
"serialNumber": ""
},
{
"type": "termination",
"description": "Termination",
"elrId": 255,
"trackId": 1100,
"miles": 0,
"chains": 37,
"serialNumber": ""
}
],
"speed": "30/60"
}
}
Errors
We return appropriate HTTP response codes whenever an error is encountered
400 Bad Request
If the URL parameter "r" is missing
401 Unauthorized
This is returned if the given signature is invalid or lapsed. A signature is valid for only 5 mins so should be generated for each request
501 Not Implemented
This is returned if "r" is supplied but is not a valid endpoint
Others
Internal errors, for example unable to contact the database or failure to encode JSON will return "400 Bad Request" unless there's a specific HTTP response associated with the error
Help
This help file can be found at https://nrsdb.uk/api/v1/help -- no authentication is required
Power BI
To access this data using Power BI;
- click Get Data / Blank Query
- enter something like = Json.Document(Web.Contents("https://training.nrsdb.uk" & "/api/v1" & "/dus/1", [Headers=[Authorization="Bearer YOUR_KEY"]]))