Table of contents

API documentation for registers

Each register has an open, RESTful API you can use to access the data, which allows you to find out information about the register. You can:

  • get all the records from the register
  • find records that share attributes with each other
  • download the whole or part of the register
  • find a single record, entry or item

Registers only provide raw data. You cannot use the APIs to search a register or match data. Depending on your requirements, you may have to build indexes on top of a register to fulfil specific requests.

Quick start guide

Generate an API key

Create your API key and fill in the requested information. Your API key will be displayed and emailed to you.

Your API key can be used for all registers.

Authenticate with your API key

You should include your key in all requests using the Authorization header:

curl https://country.register.gov.uk/records/GB.json --header 'Authorization: YOUR-API-KEY-HERE'

Find the base URL for register(s)

Find the base URL for each register on its API inspector. For example, the API inspector for the local-authority-eng register is located at https://local-authority-eng.register.gov.uk/.

The following are some examples of base URLs:

Register ID Base URL
local-authority-eng https://local-authority-eng.register.gov.uk/
country https://country.register.gov.uk/
allergen https://allergen.register.gov.uk/

Choose an endpoint

Using different endpoints, you can:

Choose a response format

Choose a response format by adding the appropriate suffix to the request URL:

Format Suffix Media type
JSON .json application/json
YAML .yaml text/yaml
CSV .csv text/csv
TSV .tsv text/tab-separated-values
Turtle .ttl text/turtle

For example:

curl https://country.register.gov.uk/records/GB.json --header 'Authorization: YOUR-API-KEY-HERE'

You can also specify a format by making a request with the Accept header. For example:

curl https://country.register.gov.uk/records/GB --header 'Accept: application/json' --header 'Authorization: YOUR-API-KEY-HERE'

Pagination

API calls on resource collections are paginated. Follow the specific guidance for each endpoint to get the page(s) of entries and records you need. For example, to paginate the records’ collection use page-size to define the amount of elements you want per page and page-index to define the page you want to get. The maximum page-size is 5000.

API reference

GET /register/

Get information about a register.

GET /register/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json

{
  "domain": "register.gov.uk",
  "total-records": 354,
  "total-entries": 358,
  "register-record": {
    "fields": [
      "local-authority-eng",
      "local-authority-type",
      "name",
      "official-name",
      "start-date",
      "end-date"
    ],
    "registry": "department-for-communities-and-local-government",
    "text": "Local authorities in England",
    "phase": "beta",
    "register": "local-authority-eng"
  },
  "custodian": "Mark Coram",
  "last-updated": "2017-07-04T10:55:43Z"
}

GET /records/

Get all records from a register.

Parameters:

  • page-index (Optional): Collection page number. Defaults to 1.
  • page-size (Optional): Collection page size. Defaults to 100. Maximum is 5000.
GET /records/?page-index=1&page-size=3 HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json
Link: <?page-index=2&page-size=3>; rel="next"

{  
   "KIN":{  
      "index-entry-number":"357",
      "entry-number":"357",
      "entry-timestamp":"2017-01-26T12:34:10Z",
      "key":"KIN",
      "item":[  
         {  
            "local-authority-type":"NMD",
            "official-name":"Borough Council of King's Lynn and West Norfolk",
            "local-authority-eng":"KIN",
            "name":"King's Lynn and West Norfolk"
         }
      ]
   },
   "GLA":{  
      "index-entry-number":"356",
      "entry-number":"356",
      "entry-timestamp":"2016-11-01T14:16:54Z",
      "key":"GLA",
      "item":[  
         {  
            "local-authority-type":"SRA",
            "official-name":"Greater London Authority",
            "local-authority-eng":"GLA",
            "name":"Greater London",
            "start-date":"1905-06-22"
         }
      ]
   },
   "LND":{  
      "index-entry-number":"355",
      "entry-number":"355",
      "entry-timestamp":"2016-10-31T12:59:03Z",
      "key":"LND",
      "item":[  
         {  
            "local-authority-type":"CC",
            "official-name":"City of London Corporation",
            "local-authority-eng":"LND",
            "name":"City of London",
            "start-date":"1905-06-28"
         }
      ]
   }
}

GET /records/{key}/

Get a specific record within a register based on a particular key.

Parameters:

  • key (Required): A unique UTF-8 string which identifies something in a register.
GET /records/KIN HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json

{
  "KIN": {
    "index-entry-number": "357",
    "entry-number": "357",
    "entry-timestamp": "2017-01-26T12:34:10Z",
    "key": "KIN",
    "item": [
      {
        "local-authority-type": "NMD",
        "official-name": "Borough Council of King's Lynn and West Norfolk",
        "local-authority-eng": "KIN",
        "name": "King's Lynn and West Norfolk"
      }
    ]
  }
}

GET /records/{key}/entries/

Get all entries for a single record based on a particular key.

Parameters:

  • key (Required): A unique UTF-8 string which identifies something in a register.
GET /records/KIN/entries/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json

[
  {
    "index-entry-number": "265",
    "entry-number": "265",
    "entry-timestamp": "2016-10-21T16:11:20Z",
    "key": "KIN",
    "item-hash": [
      "sha-256:5a8571fc6e78f8688c66b72ea45f921a7cd1562b9a9b5b9dab8f49f842d1e391"
    ]
  },
  {
    "index-entry-number": "357",
    "entry-number": "357",
    "entry-timestamp": "2017-01-26T12:34:10Z",
    "key": "KIN",
    "item-hash": [
      "sha-256:3f4da33a33c24de11cca3539f14ee663359608be0ba218d4fc05792c1d19c00f"
    ]
  }
]

GET /records/{field-name}/{field-value}/

Get all records that share a field-value for a particular field-name.

Parameters:

  • field-name (Required): Field name.
  • field-value (Required): Field value.
  • page-index (Optional): Collection page number. Defaults to 1.
  • page-size (Optional): Collection page size. Defaults to 100. Maximum is 5000.
GET /records/local-authority-type/CTY/?page-index=1&page-size=3 HTTP/1.1 
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json
Link: <?page-index=2&page-size=3>; rel="next"

{  
   "NTH":{  
      "index-entry-number":"269",
      "entry-number":"269",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"NTH",
      "item":[  
         {  
            "local-authority-type":"CTY",
            "official-name":"Northamptonshire County Council",
            "local-authority-eng":"NTH",
            "name":"Northamptonshire"
         }
      ]
   },
   "WAR":{  
      "index-entry-number":"334",
      "entry-number":"334",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"WAR",
      "item":[  
         {  
            "local-authority-type":"CTY",
            "official-name":"Warwickshire County Council",
            "local-authority-eng":"WAR",
            "name":"Warwickshire"
         }
      ]
   },
   "HRT":{  
      "index-entry-number":"208",
      "entry-number":"208",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"HRT",
      "item":[  
         {  
            "local-authority-type":"CTY",
            "official-name":"Hertfordshire County Council",
            "local-authority-eng":"HRT",
            "name":"Hertfordshire"
         }
      ]
   },

GET /entries/

Get all entries from a register.

Parameters:

  • start (Optional): Collection page number. Defaults to 1.
  • limit (Optional): Collection page size. Defaults to 100. Maximum is 5000.
GET /entries/?start=1&limit=10 HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json
Link: <?start=11&limit=10>; rel="next"


[  
   {  
      "index-entry-number":"1",
      "entry-number":"1",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BAS",
      "item-hash":[  
         "sha-256:6c4c815895ea675857ee4ec3fb40571ce54faf5ebcdd5d73a2aae347d4003c31"
      ]
   },
   {  
      "index-entry-number":"2",
      "entry-number":"2",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BBD",
      "item-hash":[  
         "sha-256:37dd060a3efa6d5bf16f876e08fa867210f424e2e4a7989d0322218f6772332d"
      ]
   },
   {  
      "index-entry-number":"3",
      "entry-number":"3",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BDF",
      "item-hash":[  
         "sha-256:01cda95d102807943d68f71bbe7b9b290dec2ebdb15967ca66820f825ece5831"
      ]
   },
   {  
      "index-entry-number":"4",
      "entry-number":"4",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BIR",
      "item-hash":[  
         "sha-256:bdc17a29807f47a94cf612abf92fcadd2d83176f9ea419b4eeda23af2cf25ef9"
      ]
   },
   {  
      "index-entry-number":"5",
      "entry-number":"5",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BMH",
      "item-hash":[  
         "sha-256:37ca110698ea569fc229e5042830384890ab1095737f1630c9de30692cfcf973"
      ]
   },
   {  
      "index-entry-number":"6",
      "entry-number":"6",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BNH",
      "item-hash":[  
         "sha-256:792c58bf07b54a3a072c8c8a7e9b0681490e3cc76ee6e95da20434520b66d9c7"
      ]
   },
   {  
      "index-entry-number":"7",
      "entry-number":"7",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BNS",
      "item-hash":[  
         "sha-256:99d5b1631c6241b31d4c22a867802035763649efa50cc8e4c5c25a71e484d412"
      ]
   },
   {  
      "index-entry-number":"8",
      "entry-number":"8",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BOL",
      "item-hash":[  
         "sha-256:2cfa1b4bd729bde785a1fdb004c6be6a04eda3ed0ac1198401ef144b218545e0"
      ]
   },
   {  
      "index-entry-number":"9",
      "entry-number":"9",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BPL",
      "item-hash":[  
         "sha-256:0cd1103a9b0e4dcd774f6c52a4d541e8a029e78ae609b46eb1d0546df9587a6a"
      ]
   },
   {  
      "index-entry-number":"10",
      "entry-number":"10",
      "entry-timestamp":"2016-10-21T16:11:20Z",
      "key":"BRC",
      "item-hash":[  
         "sha-256:00a2c66ab69086fd9ed8d43a46e04d1577340468bd43e8fb46dcf4d6ae59c439"
      ]
   }
]

GET /entries/{entry-number}/

Get a specific entry from a register.

GET /entries/204/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json

[
  {
    "index-entry-number": "204",
    "entry-number": "204",
    "entry-timestamp": "2016-10-21T16:11:20Z",
    "key": "NEW",
    "item-hash": [
      "sha-256:53187fa5562b658b68da23fcd64bd595688ead21da3ba443531ed21164be775e"
    ]
  }
]

GET /items/{item-hash}/

Get a specific item within a register.

GET /items/sha-256:6c4c815895ea675857ee4ec3fb40571ce54faf5ebcdd5d73a2aae347d4003c31/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE
HTTP/1.1 200
Content-Type: application/json

{
  "local-authority-type": "UA",
  "official-name": "Bath and North East Somerset Council",
  "local-authority-eng": "BAS",
  "name": "Bath and North East Somerset",
  "start-date": "1996-04-01"
}

GET /download-register/

Download the full contents of the register in a ZIP file.

GET /download-register/ HTTP/1.1
Host: local-authority-eng.register.gov.uk
Accept: application/json
Authorization: YOUR-API-KEY-HERE

This will download every entry and item as an individual JSON file. If you only want to download records, use GET /records.

Getting updates

You can find the latest entry number by looking at the register information (use the GET /register endpoint) and comparing the most recent entry number with your own copy.

Example request: https://local-authority-eng.register.gov.uk/register

Download a full new copy of the register by using the GET /download-register endpoint.

Download all updates for one record according to a particular key by using the GET /records/{key}/entries endpoint:

Example URL: https://local-authority-eng.register.gov.uk/records/KIN/entries

Example request: curl --request GET --url https://local-authority-eng.register.gov.uk/records/KIN/entries --header 'Accept: application/json' --header 'Authorization: YOUR-API-KEY-HERE'

Example response:

[
  {
    "index-entry-number": "195",
    "entry-number": "195",
    "entry-timestamp": "2016-04-05T13:23:05Z",
    "key": "KIN",
    "item-hash": [
      "sha-256:d97d6b34bc572e334cbd7898f785b72947557d9dbea59977077f231274259f3b"
    ]
  },
  {
    "index-entry-number": "204",
    "entry-number": "204",
    "entry-timestamp": "2016-04-05T13:23:05Z",
    "key": "KIN",
    "item-hash": [
      "sha-256:466d194d5100532edd115e3f0035967b09bc7b7f5fc444166df6f4a5f7cb9127"
    ]
  }
]

You can then download the latest item, for example entry 204 in the above example. Use the GET /items/{item-hash} endpoint for downloading items.

Rate limits

There are no rate limits when using the registers APIs.

Linked registers

Registers can be linked by CURIEs and foreign keys.

In registers, CURIEs are a datatype, and all new registers will only be linked by CURIEs. Foreign keys are fields, and not defined by a single datatype.

You can find the datatype of any given field ({field}) at https://field.register.gov.uk/records/{field}.

CURIEs

Any value in a field with a datatype of curie must be a CURIE. In registers, all CURIEs are of the form {prefix}:{key}, where {prefix} is mapped to a base URL of the form https://{register}.register.gov.uk/records/ for a given register ({register}). This means that when the {key} is blank, it references the full set of records in that register.

For example, the organisation field (https://field.register.gov.uk/records/organisation), which appears in the statistical-geography register, has the datatype curie. In the ‘E09’ record of this register, the value of the organisation field is government-organisation:D4. The {prefix} is government-organisation, which maps to the URL https://government-organisation.register.gov.uk/records/, and the {key} is ‘D4’. The expanded URL is therefore https://government-organisation.register.gov.uk/records/D4.

Foreign keys

Some fields in registers are foreign keys which link to other registers. A given field ({field}) is a foreign key to another register if the register field is populated at https://field.register.gov.uk/records/{field}.

For example, the local-authority-type field is a foreign key, and has the URL https://field.register.gov.uk/records/local-authority-type. It’s used in the local-authority-eng register. This means that the local-authority-type field for each record in the local-authority-eng register links to a corresponding record in the local-authority-type register.

In the same example, the ‘SHE’ record of the local-authority-eng register has the URL https://local-authority-eng.register.gov.uk/records/SHE. The local-authority-type field here is populated by NMD, so this resolves to the ‘NMD’ record in the local-authority-type register, which has the URL https://local-authority-type.register.gov.uk/records/NMD.

The components of a register

Registers are primarily composed of:

  • entries
  • items
  • records

Entries

Entries contain metadata about what and when data has changed.

Entries contain the properties entry-number, entry-timestamp, item-hash and key.

The entry number is unique and defines an entry’s position within the ordered list of changes. The entry timestamp is the time when an entry was introduced to a given register, but it is no guarantee of the order of entries in a register. The entry number is.

Each entry is connected to an item by a given item hash. Entries reference items in the item-hash property using the hash derived from the corresponding item’s content.

Each key (in the key property) is a unique UTF-8 string which identifies something in a register.

Entries also contain the property index-entry-number, which is a unique number that defines an entry’s position within the ordered list of an index.

The index-entry-number property depends on indexes, which are an experimental and unreliable feature.

Items

Items contain structured data for a given primary key in a register. Items have predefined fields which are consistent within a register.

The item always contains a field which has the same name as the register. For example, every item in the local-authority-eng register has a field called local-authority-eng. The data contained in this field will be the same as the data in the key property of the entry that introduced the item to the register.

Records

A record corresponds to the latest entry for a particular key, as indicated by the entry-number property.

How entries, items and records relate

The country register, and one of its keys, ‘CI’, provides a useful example.

Using the GET /entries/{entry-number} endpoint where {entry-number} is 90 returns the 90th entry to the country register, which contains metadata. Using the GET /items/{item-hash} endpoint on that entry’s item hash returns the corresponding item, which reveals that the official-name field for the item is ‘The Republic of Cote D’Ivoire’.

The more recent 207th entry to the country register also relates to the key ‘CI’. However, this time the item hash addresses to an item that reveals that the official-name field for the corresponding item is ‘The Republic of Côte D’Ivoire’. The need to change the accent above the ‘o’ required a new entry to the register.

Using the GET /records/{key} endpoint returns the most recent entry to the register for a given {key}, with the item data already resolved. For example, GET /records/CI returns the 207th entry and its corresponding item.

Using the GET /records/CI/entries endpoint returns all entries for the key ‘CI’, meaning both the 90th and the 207th entries.

Support

Error codes

Error code Description
200 Ok
404 Data not found
500 Internal server error

If you cannot find a specific record

Check you have the correct field value. You must use the exact field value to get a match from the register.

For example, in the local-authority-eng register, you must capitalise the field value (BIR) as in https://local-authority-eng.register.gov.uk/records/BIR

Technical specification

The Government Digital Service maintains a technical specification for registers.

Contact us

Please contact the GOV.UK Registers team if you have difficulty using registers in your product or service.