Internal API

This API is designed for internal use within Network Rail. It uses a simple authentication mechanism that does not link to a specific "user" within the system. It was created in response to a request to report into Power BI.

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

Sample GET request

  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'
  });

Sample POST from a form element

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 here

Endpoints

Routes

E.g. Anglia, North-West, Wales

/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 Response

{
  "data": {
    "name": "Ipswich",
    "routeId": 2,
  }
}

ELRs

/elrs - returns all of the ELRs known to the system

/elr/{elrId} - returns the details for a specific ELR

Sample Response

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 Response

  {
  "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

See ESR data structure

GIS

/gis/nearest/{lng}/{lat} -- returns the nearest mileage marker (ELR, track, miles, chains)

/gis/w3w/{elr}?trackId=1100&miles=1&chains=0 -- returns the W3W code for the marker at the given location, trackId is optional, chains defaults to 0 if not given

Error Handling

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

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"]]))