# 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

```javascript
  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

```javascript
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

##### **<span style="color: rgb(186, 55, 42);">Routes</span>**

E.g. Anglia, North-West, Wales

<div id="bkmrk-%2Froutes---return-all"><span style="color: #000000;">/routes - return all Routes</span></div><div id="bkmrk-%2Froute%2F%7Brouteid%7D---d"><span style="color: #000000;">/route/{routeId} - detail of a specific route</span></div><div id="bkmrk-"></div>##### <span style="color: rgb(186, 55, 42); font-weight: bold;">Delivery Units</span>

<div id="bkmrk-%2Fdus---return-all-de"><span style="color: #000000;">/dus - return all Delivery Units</span></div><div id="bkmrk-%2Fdus%2Froute%2F%7Brouteid%7D"><span style="color: #000000;">/dus/route/{routeId} - return Delivery Units on a given route</span></div><div id="bkmrk-%2Fdu%2F1---get-details-"><span style="color: #000000;">/du/1 - get details for a specific DU</span></div><div id="bkmrk--1"></div><div id="bkmrk--2"></div><div id="bkmrk--3"></div><div id="bkmrk-sample-return"><span style="color: #800000; font-weight: bold;">Sample Response</span></div><div id="bkmrk--4"></div>```json
{
  "data": {
    "id": 1,
    "name": "Ipswich",
    "routeId": 2,
    "active": true
  }
}
```

<div id="bkmrk--14"></div>##### <span style="color: #800000; font-weight: bold;">ELRs</span>

<div id="bkmrk-%2Felrs---returns-all-"><span style="color: #000000;">/elrs - returns all of the ELRs known to the system</span></div><div id="bkmrk-%2Felr%2F%7Belrid%7D---retur"><span style="color: #000000;">/elr/{elrId} - returns the details for a specific ELR</span></div><div id="bkmrk--5"></div>##### <span style="color: #800000; font-weight: bold;">Locations</span>

<div id="bkmrk-%2Flocations%2F%7Belrid%7D"><span style="color: #000000;">/locations/{elrId}</span></div><div id="bkmrk-returns-the-signific"><span style="color: #000000;">Returns the significant locations along a given ELR, with Miles + Yards location and a GeoJSON marker if available</span></div><div id="bkmrk-note%3A-data-set-is-to"><span style="color: #000000;">NOTE: data set is too large to return for the entire railway</span></div><div id="bkmrk-note%3A-this-is-differ"><span style="color: #000000;">NOTE: this is different to the Autumn Inspection locations (see below)</span></div>##### <span style="color: #800000; font-weight: bold;">Autumn Inspections</span>

<div id="bkmrk-%2Fautumn%2Flocations%2F%7Br"><span style="color: #000000;">/autumn/locations/{routeId} - return all Locations to be inspected on the given route</span></div><div id="bkmrk-%2Fautumn%2Finspections-"><span style="color: #000000;">/autumn/inspections - returns all of the inspections</span></div><div id="bkmrk-%2Fautumn%2Finspections%2F"><span style="color: #000000;">/autumn/inspections/route/{routeId} - returns all inspections for a given route</span></div><div id="bkmrk--7"></div><div id="bkmrk-inspection-example-d"><span style="color: #800000; font-weight: bold;">Inspection Example Response</span></div>```json
  {
  "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": []
  }
```

<div id="bkmrk-%C2%A0-%C2%A0-%7D%2C-4"></div>##### <span style="color: #800000; font-weight: bold;">ESRs</span>

<div id="bkmrk-%2Fesrs---returns-all-"><span style="color: #000000;">/esrs - returns all known ESRs</span></div><div id="bkmrk-%2Fesrs%2Froute%2F%7Brouteid"><span style="color: #000000;">/esrs/route/{routeId} - returns ESRs for a given route</span></div><div id="bkmrk--8"></div><div id="bkmrk--9"></div><div id="bkmrk-esr-data-structure"><span style="color: #800000; font-weight: bold;">ESR Data Structure</span></div><div id="bkmrk---refnum-%28string%29---"><span style="color: #0451a5;">-</span><span style="color: #000000;"> refnum (string) - this is made up of a route specific prefix, a three digit incremental counter, plus the two digit year</span></div><div id="bkmrk---routename-%28string%29"><div id="bkmrk---speed-%28string%29---%22"><span style="color: #0451a5;">-</span><span style="color: #000000;"> speed (object) - "Freight Speed / Passenger Speed" - single number if both are same, units and unrestricted line speed</span></div><div id="bkmrk---withdrawn-%28bool%29--"></div><span style="color: #0451a5;">-</span><span style="color: #000000;"> route (object) - all properties of the route</span></div><div id="bkmrk---deliveryunit-%28stri"><span style="color: #0451a5;">-</span><span style="color: #000000;"> du (object) - responsible Delivery Unit</span></div><div id="bkmrk---elrcode-%28string%29--"><span style="color: #0451a5;">-</span><span style="color: #000000;"> elr (object) - ELR of track segment impacted e.g. LTN1</span></div><div id="bkmrk---lorid-%28int%29---inte"><span style="color: #0451a5;">-</span><span style="color: #000000;"> lor (object) - LOR properties</span></div><div id="bkmrk---location-%28string%29-"><span style="color: #0451a5;">-</span><span style="color: #000000;"> location (string) - description of where the restriction is applied</span></div><div id="bkmrk---reason-%28string%29---"><span style="color: #0451a5;">-</span><span style="color: #000000;"> reason (object) - describes reason the ESR is imposed</span></div><div id="bkmrk---withdrawn-%28bool%29---1"><span style="color: #0451a5;">-</span><span style="color: #000000;"> withdrawn (bool) - 0 = active, 1 = withdrawn</span></div><div id="bkmrk---whenimposed-%28strin"><span style="color: #0451a5;">-</span><span style="color: #000000;"> whenimposed (string) - W3C format date time string, updated during amendment</span></div><div id="bkmrk---etc-%28null%7Cstring%29-"><span style="color: #0451a5;">-</span><span style="color: #000000;"> etc (null|string) - if set this is a W3C format date time string</span></div><div id="bkmrk---whenwithdrawn-%28nul"><span style="color: #0451a5;">-</span><span style="color: #000000;"> whenwithdrawn (null|string) - if withdrawn === 1, W3C format date time string</span></div><div id="bkmrk---line-%28array%29---det"><span style="color: #0451a5;">-</span><span style="color: #000000;"> lines (array) - object for each "line". A "line" is the combination of ELR + TrackID</span></div><div id="bkmrk-%C2%A0-%C2%A0---elrid---intern"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> elr (object) - as above</span></div><div id="bkmrk-%C2%A0-%C2%A0---trackid-%28int%29-"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> trackId (int) - e.g. 1100 = Up Main</span></div><div id="bkmrk-%C2%A0-%C2%A0---direction-%28str"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> direction (string) - "Up Direction" | "Down Direction" (yuk)</span></div><div id="bkmrk-%C2%A0-%C2%A0---linedescriptio"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> linedescription (string) - can be driven by trackId or overridden by Controller</span></div><div id="bkmrk-%C2%A0-%C2%A0---routeheader-%28s"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> routeheader (string) - "Primary Line" | "Additional Line"</span></div><div id="bkmrk-%C2%A0-%C2%A0---boards-%28array%29"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> boards (array)</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---type-%28stri"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> type (string) - short name (no spaces)</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---descriptio"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> description (string) - long name</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---elrid-%28int"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> elrId (int) - copied from line</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---trackid-%28i"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> trackId (int) - copied from line</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---miles-%28int"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> miles (int) -</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---chains-%28in"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> chains (int) - 0 &gt;= X &lt; 80</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---serialnumb"><span style="color: #000000;"> </span><span style="color: #0451a5;">-</span><span style="color: #000000;"> serialNumber (string) - not currently used</span></div><div id="bkmrk-%C2%A0-%C2%A0-%C2%A0-%C2%A0---marker-%28ge"><span style="color: #000000;"> - marker (GeoJSON)</span></div><div id="bkmrk---references-%28object"><span style="color: #000000;">- references (object)</span></div><div id="bkmrk---updated_at---time-"><span style="color: #000000;">- updated\_at - time of last database change</span></div><div id="bkmrk--10"></div><div id="bkmrk-example"><span style="color: #800000; font-weight: bold;">Example Response</span></div>```json
{
  "id": 5,
  "refnum": "AICC 001.26",
  "speed": {
    "value": "40",
    "unit": "mph",
    "linespeed": "120"
  },
  "route": {
    "id": 2,
    "routecode": "EA",
    "routename": "Anglia",
    "shortname": "AICC",
    "active": true
  },
  "du": {
    "id": 1,
    "name": "Ipswich",
    "routeId": 2,
    "active": true
  },
  "elr": {
    "elrId": 668,
    "elrcode": "LTN1",
    "elrdescription": "LIVERPOOL STREET - TROWSE LOWER JN",
    "active": true
  },
  "lor": {
    "id": 2,
    "lorcode": "EA1011",
    "lordescription": "SEVEN KINGS TO IPSWICH",
    "active": true
  },
  "location": "At Colchester South Jn",
  "reason": {
    "id": 18,
    "reason": "Structural - Station",
    "active": true
  },
  "lines": [
    {
      "elr": {
        "elrId": 668,
        "elrcode": "LTN1",
        "elrdescription": "LIVERPOOL STREET - TROWSE LOWER JN",
        "active": true
      },
      "trackId": 1100,
      "routeheader": "Primary Line",
      "direction": "Up Direction",
      "linedescription": "Up Main",
      "newStyleBoards": true,
      "boards": [
        {
          "type": "commencement",
          "description": "Speed Indicator (Commencement)",
          "elrId": 668,
          "trackId": 1100,
          "miles": 50,
          "chains": 75,
          "serialNumber": null,
          "marker": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                0.876876605,
                51.90208042
              ]
            },
            "properties": {
              "type": "commencement",
              "description": "Speed Indicator (Commencement)",
              "elrId": 668,
              "trackId": 1100,
              "miles": 50,
              "chains": 75,
              "serialNumber": null
            }
          }
        },
        {
          "type": "termination",
          "description": "Termination Indicator",
          "elrId": 668,
          "trackId": 1100,
          "miles": 49,
          "chains": 75,
          "serialNumber": null,
          "marker": {
            "type": "Feature",
            "geometry": {
              "type": "Point",
              "coordinates": [
                0.85427535,
                51.89894058
              ]
            },
            "properties": {
              "type": "termination",
              "description": "Termination Indicator",
              "elrId": 668,
              "trackId": 1100,
              "miles": 49,
              "chains": 75,
              "serialNumber": null
            }
          }
        }
      ]
    }
  ],
  "whenimposed": "2026-03-18 11:42:06",
  "etr": null,
  "withdrawn": false,
  "whenwithdrawn": null,
  "references": {
    "fmsnumber": "123",
    "ccilnumber": "23645657",
    "tsrreference": "",
    "tdanumber": "",
    "wo": "",
    "rdms": "",
    "trustcode": "",
    "owner": ""
  },
  "updated_at": "2026-03-18 11:42:06"
}
```

##### GIS

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

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

### <span style="color: #800000; font-weight: bold;">Error Handling</span>

<div id="bkmrk-we-return-appropriat"><span style="color: #000000;">We return appropriate HTTP response codes whenever an error is encountered</span></div><div id="bkmrk-400-bad-request"><span style="color: #800000; font-weight: bold;">400 Bad Request</span></div><div id="bkmrk-if-the-url-parameter"><span style="color: #000000;">If the URL parameter "r" is missing</span></div><div id="bkmrk-401-unauthorized"><span style="color: #800000; font-weight: bold;">401 Unauthorized</span></div><div id="bkmrk-this-is-returned-if-"><span style="color: #000000;">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</span></div><div id="bkmrk-501-not-implemented"><span style="color: #800000; font-weight: bold;">501 Not Implemented</span></div><div id="bkmrk-this-is-returned-if--1"><span style="color: #000000;">This is returned if "r" is supplied but is not a valid endpoint</span></div><div id="bkmrk-others"><span style="color: #800000; font-weight: bold;">Others</span></div><div id="bkmrk-internal-errors%2C-for"><span style="color: #000000;">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</span></div><div id="bkmrk--11"></div>### <span style="color: #800000; font-weight: bold;">Help</span>

<div id="bkmrk-this-help-file-can-b"><span style="color: #000000;">This documentation can also be found at https://nrsdb.uk/api/v1/help -- no authentication is required</span></div>##### <span style="color: #800000; font-weight: bold;">Power BI</span>

<div id="bkmrk-to-access-this-data-"><span style="color: #000000;">To access this data using Power BI;</span></div><div id="bkmrk---click-get-data-%2F-b"><span style="color: #0451a5;">-</span><span style="color: #000000;"> click Get Data / Blank Query</span></div><div id="bkmrk---enter-something-li"><span style="color: #0451a5;">-</span><span style="color: #000000;"> enter something like = Json.Document(Web.Contents("https://training.nrsdb.uk" &amp; "/api/v1" &amp; "/dus/1", \[Headers=\[Authorization="Bearer YOUR\_KEY"\]\]))</span></div><div id="bkmrk--12"></div>