# 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

- <span style="color: #000000;">/routes - return all Routes</span>
- <span style="color: #000000;">/route/{routeId} - detail of a specific route</span>

<div id="bkmrk-"></div>##### <span style="color: rgb(186, 55, 42); font-weight: bold;">Delivery Units</span>

- <span style="color: #000000;">/dus - return all Delivery Units</span>
- <span style="color: #000000;">/dus/route/{routeId} - return Delivery Units on a given route</span>
- <span style="color: #000000;">/du/1 - get details for a specific DU</span>

<div id="bkmrk--1"></div><div id="bkmrk--2"></div><div id="bkmrk--3"></div><div id="bkmrk--4"></div><span style="color: #800000; font-weight: bold;">Sample Response</span>

<div id="bkmrk--5"></div>```json
{
  "data": {
    "name": "Ipswich",
    "routeId": 2,
  }
}
```

<div id="bkmrk--14"></div>##### <span style="color: rgb(224, 62, 45); font-weight: bold;">ELRs</span>

- <span style="color: #000000;">/elrs - returns all of the ELRs known to the system</span>
- <span style="color: #000000;">/elr/{elrId} - returns the details for a specific ELR</span>

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

```json
{
  "data": {
    "elrs": [
      {
        "id": 1,
        "elrcode": "AAV",
        "elrdescription": "ASCOT JN - ASH VALE JN",
        "active": true
      },
      {
        "id": 2,
        "elrcode": "ABD",
        "elrdescription": "ABERDARE  BRANCH",
        "active": true
      },
      ...
    ]
  }
}

```

<div id="bkmrk--8"></div><div id="bkmrk--9"></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>

- <span style="color: #000000;">/autumn/locations/{routeId} - return all Locations to be inspected on the given route</span>
- <span style="color: #000000;">/autumn/inspections - returns all of the inspections</span>
- <span style="color: #000000;">/autumn/inspections/route/{routeId} - returns all inspections for a given route</span>

<div id="bkmrk--10"></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>

- <span style="color: #000000;">/esrs</span>
- <span style="color: #000000;">/esrs/route/{routeId} - returns ESRs for a given route</span>

<div id="bkmrk--11"></div><div id="bkmrk--12"></div><div id="bkmrk--13"></div><div id="bkmrk-see-esr-data-structu"><span style="color: #000000;">See [ESR data structure](https://docs.nrsdb.uk/books/nrsdb-api/page/data-structures "Data Structures")</span></div><div id="bkmrk--15"></div><div id="bkmrk--16"></div><div id="bkmrk-add-an-%22age%22-paramet"><span style="color: #000000;">Add an "age" parameter to return ESRs imposed, amended or withdrawn within the given number of days. If age is not given we assume 365 days. E.g.</span></div><div id="bkmrk--17"></div><div id="bkmrk--18"></div><div id="bkmrk-https%3A%2F%2Fnrsdb.uk%2Fapi-1"><span style="color: #000000;">https://nrsdb.uk/api/v1/esrs/route/2?age=3</span></div>##### <span style="color: rgb(186, 55, 42);">**GIS**</span>

- /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--19"></div><div id="bkmrk-this-help-file-can-b"></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://nrsdb.uk" &amp; "/api/v1" &amp; "/dus/1", \[Headers=\[Authorization="Bearer YOUR\_SECRET"\]\]))</span></div><div id="bkmrk--20"></div>