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/tsv
Turtle .ttl text/ttl

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

View information about a register, including:

  • the internet domain the register is on
  • when the register was last updated
  • how many entries and records the register contains

You can check the entry number you have locally is up to date with the register by comparing the value of total-entries for each.

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

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

Example response:

{
  "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 the register. For example, all of the English local authorities from the local-authority-eng register.

Results from this API call are paginated. This call will return the first 100 records from the first page of the register. Use page-size to define the number of records you want and page-index to define the pages you want. The maximum page-size is 5000.

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

Example request: curl --request GET --url 'https://local-authority-eng.register.gov.uk/records?page-index=1&page-size=3' --header 'Accept: application/json' --header 'Authorization: YOUR-API-KEY-HERE'

Example response:

{  
   "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. For example, the record for the Borough Council of King’s Lynn and West Norfolk in the local-authority-eng register.

You must have the exact field value of the unique identifier for the record to get a match from the register. For example, in the local-authority-eng register, the field value of the unique identifier (the three-letter code for the county council) must be in capital letters.

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

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

Example response:

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

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": "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"
    ]
  }
]

You can then download the latest item. For example, entry 265 in the above code snippet. Follow the guidance for downloading items.

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

Get all records that share a field-value for a particular field. For example, all local authorities marked as county councils from the local-authority-eng register.

Results from this API call are paginated. This call will return the first 100 records from the first page of the register. Use page-size to define the number of records you want and page-index to define the pages you want. The maximum page-size is 5000.

Example URL: https://local-authority-eng.register.gov.uk/records/local-authority-type/CTY

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

Example response:

{  
   "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 the register. For example, all updates there have ever been to the local-authority-eng register.

Results from this API call are paginated. This call will return the first 100 entries from the first page of the register. Use limit to define the maximum number of entries you want and start to define the entry number you want to start from (in ascending order).

Example URL: https://local-authority-eng.register.gov.uk/entries?start=1&limit=10

Example request: curl --request GET --url 'https://local-authority-eng.register.gov.uk/entries?start=1&limit=10' --header 'Accept: application/json' --header 'Authorization: YOUR-API-KEY-HERE'

Example response:

[  
   {  
      "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. For example, an update to the record for the New Forest District Council in the local-authority-eng register. An entry can include multiple items, which will return in a list of item-hash

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

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

Example response:

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

Example URL: https://local-authority-eng.register.gov.uk/items/sha-256:6c4c815895ea675857ee4ec3fb40571ce54faf5ebcdd5d73a2aae347d4003c31

Example request: curl --request GET --url https://local-authority-eng.register.gov.uk/items/sha-256:6c4c815895ea675857ee4ec3fb40571ce54faf5ebcdd5d73a2aae347d4003c31 --header 'Accept: application/json' --header 'Authorization: YOUR-API-KEY-HERE'

Example response:

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

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

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

Example request: curl -o localauthorityeng.zip --request GET --url https://local-authority-eng.register.gov.uk/download-register --header 'Authorization: YOUR-API-KEY-HERE'

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 GDS Registers team if you have difficulty using registers in your product or service.