Table of contents

API documentation for registers

Each register has an open API you can use to access the data without any authentication. There are no rate limits.

Each register API allows you to:

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

The base URL for each register API is of the form: https://{register name}.register.gov.uk/

You can find the base URL for each register by looking at the list of available registers.

Most of the APIs return paginated results. See the API reference to get the page(s) of entries, items, and records you need.

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 fulfill specific requests.

Contact the GDS registers team if you have any problems or questions that are not covered in this guide.

Quick start guide

  1. Find the base URL for the register(s) you want to use
  2. Find the endpoints you want.
  3. Add .json, .yaml, .csv, .tsv, or .ttl to the end of the request URL (before any query parameters) to choose the format of the response, or amend headers to accept application/json or equivalent.
  4. Parse register data and use it in your product or service.

Most of the API functions return paginated results. Follow the specific guidance for each endpoint to get the page(s) of entries, items, and records you need. Use page-size to define the number of results you want and page-index to define the pages you want. The maximum page-size is 5000.

API reference

Find out more about a register

Path: 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

Example URL: https://country.register.gov.uk/register

Example request: curl --request GET --url https://country.register.gov.uk/register --header 'accept: application/json'

Example response:

{  
   "domain":"register.gov.uk",
   "total-records":199,
   "total-entries":206,
   "register-record":{  
      "fields":[  
         "country",
         "name",
         "official-name",
         "citizen-names",
         "start-date",
         "end-date"
      ],
      "registry":"foreign-commonwealth-office",
      "text":"British English-language names and descriptive terms for countries",
      "phase":"beta",
      "register":"country",
      "entry-timestamp":"2016-08-04T14:45:41Z",
      "key":"country",
      "index-entry-number":"2",
      "entry-number":"2"
   },
   "last-updated":"2017-03-29T14:22:30Z"
}

Get all records

Path: GET /records

Get all records from the register. For example, all of the countries from the country register.

Note: 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'

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

View a specific record

Path: GET /record/{field-value}

Find a specific record within a register. For example, the record for Vatican City in the country register.

Note: You must have the exact field value of the unique identifier for the record to get a match from the register. In the country register, for example, the field value of the unique identifier, the ICO country code, must be in capital letters.

Example URL: https://country.register.gov.uk/record/VA

Example request: curl --request GET --url https://country.register.gov.uk/record/VA --header 'accept: application/json'

Example response:

{  
   "VA":{  
      "index-entry-number":"204",
      "entry-number":"204",
      "entry-timestamp":"2016-04-05T13:23:05Z",
      "key":"VA",
      "item":[  
         {  
            "country":"VA",
            "official-name":"Vatican City State",
            "name":"Vatican City",
            "citizen-names":"Vatican citizen"
         }
      ]
   }
}

View records that share attributes

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

Find all records that share a field-value for a particular field. For example, all schools marked as Quaker schools from the school register.

Note: 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'

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

View all entries

Path: GET /entries

Get all entries from the register. For example, all updates there have ever been to the country register.

Note: Results from this API call are paginated. This call will return the first 100 entries from the first page of the register. Use page-size to define the number of entries 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/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'

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

View a specific entry

Path: GET /entry/{entry-number}

Find a specific entry from a register. For example, an update to the record for the USSR in the country register. An entry can include multiple items, which will return in a list of item-hash

Example URL: https://country.register.gov.uk/entry/204

Example request: curl --request GET --url https://country.register.gov.uk/entry/204 --header 'accept: application/json'

Example response:

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

View a specific item

Path: GET /item/{item-hash}

Find a specific item within a register.

Example URL: https://country.register.gov.uk/item/sha-256:466d194d5100532edd115e3f0035967b09bc7b7f5fc444166df6f4a5f7cb9127

Example request: curl --request GET --url https://country.register.gov.uk/item/sha-256:466d194d5100532edd115e3f0035967b09bc7b7f5fc444166df6f4a5f7cb9127 --header 'accept: application/json'

Example response:

{
  "country": "VA",
  "official-name": "Vatican City State",
  "name": "Vatican City",
  "citizen-names": "Vatican citizen"
}

Download the full register

Path: GET /download-register

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

Note: 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 country.zip --request GET --url https://local-authority-eng.register.gov.uk/download-register

Getting updates

You can download the new entries in 2 ways:

  • download another copy of the full register
  • download individual updated entries for the records you are using

Check for updates

Path: GET /register

You can find the latest entry number by looking at the register information and comparing the most recent entry number with your own copy.

Example request: https://country.register.gov.uk/register

Download a full new copy of the register

See endpoint for downloading register.

Download all updates for one record

Path: GET /record/{field-value}/entries

Get all entries for a single record.

Example URL: https://country.register.gov.uk/record/VA/entries

Example request: curl --request GET --url https://country.register.gov.uk/record/VA/entries --header 'accept: application/json'

Example response:

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

You can then download the latest item, for example entry 204 in the above example. Follow the guidance for downloading items.

Rate limits

There are no rate limits when using the registers APIs.

Contact the GDS registers team at registerteam@digital.cabinet-office.gov.uk if you have any questions.

Case studies

GOV.UK Pay, the Department for International Development (DFID), and the e-petitions service are among the users of registers.

E-petitions

The UK Government and Parliament petitions service uses the country register to populate a drop-down menu.

To sign a petition, users are asked to select their location. The menu options come from the country register. The petitions service team have added additional areas that are not recognised as official countries by the FCO, for example Taiwan and the Occupied Palestinian Territories. Because the menu includes more than just countries, the service team have labelled the field ‘Location’ rather than ‘Country’.

The initial values in the database are set by a migration script, which has a hardcoded snapshot of the country register at a point in time, along with some other hardcoded locations such as American Samoa.

Every night, the e-petitions team run a job to read the country register and update every matching location in the database if it has changed. There are other locations in the table which are not in the country register and are left alone by the job.

Support and community

GDS maintains the platform behind registers and helps custodians to run their registers. Custodians are expected to keep their registers data up to date.

GDS provides operational support from 09:00 - 17:00 Monday-Friday.

Contact the GDS registers team if you have any problems or questions that are not covered in this guide. Please include error messages if relevant.

The GDS registers team blog about their progress on the Data in Government blog and the GDS blog. Previous posts include:

GDS also maintains a technical specification for registers.

Error codes

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

Common issues

Please find information below about common problems when using registers. If your issue is not included or you are struggling to use registers in your product or service, please contact the GDS registers team.

Registers still in beta

Despite the beta label, registers in beta are reliable to use in products and services.

If you can’t find a specific record

If you can’t 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 country register the field value must be in capital letters.

Incorrect request: https://country.register.gov.uk/record/gb

Correct request: https://country.register.gov.uk/record/GB

End-date field

The end-date field is used to note when an entry ceases to be valid. For example, in the country register, the end-date field contains the date when a country was dissolved or changed its name. For example, the end-date field value for East Germany is 1990-10-02.

You may need to remove records with an end-date if your product or service only requires data on existing countries.

Missing countries in country register

The country register only contains countries recognised by the Foreign and Commonwealth Office. As such, the country register does not contain territories such as Gibraltar and the Occupied Palestinian Territories. These are included in the territories register, which is in discovery.

Adding additional data

If you want to combine register data with data from other sources, it can be useful to keep the data from each source in separate files and combine them at a later stage. For example, you could keep separate files for data about countries and data about territories.

Glossary

custodian - The person who is responsible for the data in the register. They’re from the government department or agency responsible for the information in the register. They make sure the register is accurate and up-to-date.

entry - An entry describes how a record has changed over time. An entry is a particular set of fields and values that were correct at one point in time. Entries are ordered by when they were added to a register.

field - A data structure for a single piece of data and they are the smallest part of a register. Every item contains a set of fields. In the country register, fields include country, name, official-name, and citizen-name. Each field is a name that is used consistently between open registers. A list of all the fields that are used in open registers are kept in the field register.

item - An item is made up of fields and values containing information. Items are the actual data contained within a register. For example, in the record for Great Britain in the country register, an item would be its country name, ‘United Kingdom’ and its official citizen name, ‘Briton;British citizen’.

Items are connected to entries with an item hash, an algorithm that maps data of arbitrary size to a byte string of fixed size. A hash is unique to its item and no item will have the same item-hash as another item, unless the item contains exactly the same information. For example, in the country register the item hash sha-256:d97d6b34bc572e334cbd7898f785b72947557d9dbea59977077f231274259f3b links that item with entry 195, which in turn is tied to the record for Vatican City.

record - A record contains all the information about a single thing in a register. For example, in the country register, there are currently 199 records, one for each country recognised by the Foreign and Commonwealth Office. A record points to the most recent entry.

register - A list of information designed to be an accurate and up-to-date source of data from government. Once entered into a register, the contents can only be added to, they cannot be deleted or rewritten.

primary key - A numeric or alphanumeric string. Records define themselves by a unique identifier associated with a single record in a register. A unique identifier can be a candidate for a primary key. The primary key always has the same name as the name of the register. For example, every entry in the country register has a field called country. This helps to link that entry specifically to the country register.