Back

Use land and property data

API technical documentation

This is technical information for software engineers who will access Use land and property data using the API.

API overview

This API is used as way to access datsets programatically. By creating an account you get an API key by default, which is used to call the endpoints.

Authentication

The Use land and property data API uses a key to authenticate you. We'll ask for authentication on every request.

The API Key should be given on every request as the Authorization header.

It is also advisable to pass in the Accept header with the value of application/json to ensure you get the correct responses when querying the API.

Parameters

Following Restful API standards, any parameters should be passed to endpoints as URL encoded parameters.

URL

The URL for all endpoints should be:

https://use-land-property-data.service.gov.uk/api/v1/{endpoint}

{endpoint} should be replaced by a suitable endpoint name below.

Definition of terms

The dataset names have changed.

ccod is now called UK companies that own property in England and Wales
ocod is now called Overseas companies that own property in England and Wales

The terms CCOD and OCOD are still used in the file name and dataset name variables.

file name - CCOD_FULL_2019_08.zip
dataset name - ccod

Endpoints

/datasets

returns a JSON list of the dataset names and titles that are available in the service.

Methods available: GET

Parameters:

None

JSON Object

Example:

            
{
"result": [
    {
    "name": "ccod",
    "title": "UK companies that own property in England and Wales"
    },
    {
    "name": "ocod",
    "title": "Overseas companies that own property in England and Wales"
    },
    {
    "name": "nps",
    "title": "National Polygon Service"
    },
    {
    "name": "nps_sample",
    "title": "National Polygon Service Sample"
    }
],
"success": true
}

/datasets/{dataset_name}

Returns the metadata of a dataset and its resources

Methods available: GET

Parameters:

None

JSON Object

Example:

            
{
"result": {
    "description": "Download data about UK companies that own land or property in England and Wales. This data includes (where available) company name, type of company, registration number, address and price paid. This data was originally called Commercial and corporate data (CCOD).",
    "external": false,
    "fee": "Free of charge",
    "file_count": 1,
    "file_size": "1.23 MB",
    "format": "CSV",
    "last_updated": "7 August 2019",
    "licence_id": "ccod",
    "name": "ccod",
    "private": false,
    "public_resources": [
    {
        "file_count": 1,
        "file_name": "example.csv",
        "file_size": "10 B",
        "format": "CSV",
        "name": "Example Data",
        "row_count": 1
    }
    ],
    "resources": [
    {
        "file_count": 1,
        "file_name": "CCOD_COU_2019_09.zip",
        "file_size": "1.3 MB",
        "format": "CSV",
        "name": "Change Only File",
        "row_count": 4138
    },
    {
        "file_count": 1,
        "file_name": "CCOD_FULL_2019_09.zip",
        "file_size": "1.23 MB",
        "format": "CSV",
        "name": "Full File",
        "row_count": 4138
    }
    ],
    "state": "active",
    "tech_spec_url": "https://www.gov.uk/government/publications/overseas-companies-ownership-data-technical-specification",
    "title": "UK companies that own property in England and Wales",
    "type": "free",
    "update_frequency": "Monthly",
    "version": "v1"
},
"success": true
}

datasets/{dataset_name}/{file_name}

Returns a download URL valid for 10 seconds for a specific file in a dataset

Note: This endpoint will only work if you have agreed to the dataset licence and have the correct access. You can do this on the Use land and property data service.

Methods available: GET

Parameters:

None

JSON Object

Example:

            
{
"result": {
    "download_url": "https://bucket.s3.amazonaws.com/ccod/CCOD_COU_2019_09.zip?response-content-type=application%2Fforce-download&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2UQ4ZYORJ3Q7HI7G%2F20191129%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20191129T121417Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host&X-Amz-Signature=44778c5d5c0183ae3d1147eff91822936cd0f114845e8ec384ffc8c5927717cb",
    "resource": "CCOD_COU_2019_09.zip",
    "valid_for_seconds": 10
},
"success": true
}

/datasets/history/{dataset_name}

Returns a list of available historical resources for a dataset.

Methods available: GET

Overseas companies that own property in England and Wales (OCOD) was published quarterly before November 2017.

UK companies that own property in England and Wales (CCOD) was published quarterly and had a different structure before November 2017.
Read the technical specification for these files.

Parameters:

None

JSON Object

Example:

                
{

    "success": true,
    "dataset": "ccod",
    "dataset_history": [
        {
        "file_size": "1.3 MB",
        "filename": "CCOD_COU_2019_08.zip",
        "last_updated": "August 2019",
        "unsorted_date": "07-08-2019"
        },
        {
        "file_size": "1.23 MB",
        "filename": "CCOD_FULL_2019_08.zip",
        "last_updated": "August 2019",
        "unsorted_date": "07-08-2019"
        },
        {
        "file_size": "577.91 KB",
        "filename": "CCOD_COU_2019_07.zip",
        "last_updated": "July 2019",
        "unsorted_date": "29-07-2019"
        },
        {
        "file_size": "542.35 KB",
        "filename": "CCOD_FULL_2019_07.zip",
        "last_updated": "July 2019",
        "unsorted_date": "29-07-2019"
        },
        {
        "file_size": "60.24 MB",
        "filename": "CCOD_COU_2019_06.zip",
        "last_updated": "June 2019",
        "unsorted_date": "03-06-2019"
        },
        {
        "file_size": "1.3 GB",
        "filename": "CCOD_FULL_2019_06.zip",
        "last_updated": "June 2019",
        "unsorted_date": "03-06-2019"
        },
        {
        "file_size": "37.03 KB",
        "filename": "CCOD_COU_2019_05.zip",
        "last_updated": "May 2019",
        "unsorted_date": "01-05-2019"
        },
        {
        "file_size": "35.3 KB",
        "filename": "CCOD_FULL_2019_05.zip",
        "last_updated": "May 2019",
        "unsorted_date": "01-05-2019"
        },
        {
        "file_size": "37.03 KB",
        "filename": "CCOD_COU_2019_05.zip",
        "last_updated": "April 2019",
        "unsorted_date": "01-04-2019"
        },
        {
        "file_size": "35.3 KB",
        "filename": "CCOD_FULL_2019_05.zip",
        "last_updated": "April 2019",
        "unsorted_date": "01-04-2019"
        },
        {
        "file_size": "37.03 KB",
        "filename": "CCOD_COU_2019_03.zip",
        "last_updated": "March 2019",
        "unsorted_date": "01-03-2019"
        },
        {
        "file_size": "35.3 KB",
        "filename": "CCOD_FULL_2019_03.zip",
        "last_updated": "March 2019",
        "unsorted_date": "01-03-2019"
        },
        {
        "file_size": "37.03 KB",
        "filename": "CCOD_COU_2019_02.zip",
        "last_updated": "February 2019",
        "unsorted_date": "01-02-2019"
        },
        {
        "file_size": "35.3 KB",
        "filename": "CCOD_FULL_2019_02.zip",
        "last_updated": "February 2019",
        "unsorted_date": "01-02-2019"
        },
        {
        "file_size": "37.03 KB",
        "filename": "CCOD_COU_2019_05.zip",
        "last_updated": "January 2019",
        "unsorted_date": "01-01-2019"
        },
        {
        "file_size": "35.3 KB",
        "filename": "CCOD_FULL_2019_05.zip",
        "last_updated": "January 2019",
        "unsorted_date": "01-01-2019"
        }
    ]
}

datasets/history/{dataset_name}/{file_name}

Returns a download URL valid for 10 seconds for a specific historical file for the provided dataset

Note: This endpoint will only work if you have agreed to the dataset licence and have the correct access. You can do this on the Use land and property data service.

Methods available: GET

Parameters:

None

JSON Object

Example:

                
{
    "success": true,
    "result": {
        "download_url": "https://datapub-integration-bucket.s3.amazonaws.com/ccod/history/2019_02/CCOD_COU_2019_02.zip?response-content-type=application%2Fforce-download&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2UQ4ZYORJ3Q7HI7G%2F20191219%2Feu-west-2%2Fs3%2Faws4_request&X-Amz-Date=20191219T133951Z&X-Amz-Expires=10&X-Amz-SignedHeaders=host&X-Amz-Signature=2f5c974977a110ad9d2a4aaf3ce4253c73f37ab237e33b30cbef7ef18bbb9146",
        "resource": "CCOD_COU_2019_02.zip",
        "valid_for_seconds": 10
    }
}

Response codes

200 OK

The user request was successful.

Request example

https://use-land-property-data.service.gov.uk/api/v1/datasets

Response example

            
{
"result": [
    {
    "name": "ccod",
    "title": "UK companies that own property in England and Wales"
    },
    {
    "name": "ocod",
    "title": "Overseas companies that own property in England and Wales"
    },
    {
    "name": "nps",
    "title": "National Polygon Service"
    },
    {
    "name": "nps_sample",
    "title": "National Polygon Service Sample"
    }
],
"success": true
}

Error response codes

403 forbidden

The user is not authorised to use the API.

This could happen if the user:

does not provide an API key
has not agreed to the dataset licence
does not have access to the request dataset, if it is a paid datset for example

Request example 1

https://use-land-property-data.service.gov.uk/api/v1/datasets

Response example 1

            
{
"error": "Access denied: You need to provide your API Key to perform this operation",
"success": false
}

Request example 2

https://use-land-property-data.service.gov.uk/api/v1/datasets/ocod/OCOD_COU_2019_10.zip

Response example 2

            
{
"error": "You have not yet signed the licence for this dataset",
"success": false
}

Request example 3

https://use-land-property-data.service.gov.uk/api/v1/datasets/nps/NSD_COU_2019_08.zip

Response example 3

            
{
"error": "You have not paid for access to this dataset",
"success": false
}

404 Not found

The user has requested something that does not exist.

This could happen if the user:

enters a URL that cannot be found
the API key that you entered has expired, is incorrect or does not exist
the resource/file name provided does not exist

Request example 1

https://use-land-property-data.service.gov.uk/api/v1/non_existent_resource

Response example 1

{}

Request example 2

https://use-land-property-data.service.gov.uk/api/v1/datasets

Response example 2

            
{
"error": "API Key provided is incorrect or does not exist",
"success": false
}

Request example 3

https://use-land-property-data.service.gov.uk/api/v1/datasets/ocod/INVALID_FILE_NAME.zip

Response example 3

            
{
"error": "The File name provided does not exist",
"success": false
}

500 Internal server error

There is an undefined error in the server.

Response example

{ }

Suggested resolution

Read the API documentation to check you are using the API as instructed.

There may be a problem with the service. Try again in a few minutes or get in contact.

Support

Use our online contact form if you:

need help using the service
want to report a problem
want to leave feedback

You can also contact us via:

Telephone

Telephone: 0300 006 0478
Monday to Friday, 9am to 5pm

Find out about call charges

Email

data.services@mail.landregistry.gov.uk
We aim to respond within 2 working days

Address

Data Services Team
HM Land Registry
Rosebrae Court
Woodside Ferry Approach
Birkenhead
Merseyside
CH41 6DU

Cookies on Use land and property data

API technical documentation

API overview

Authentication

Parameters

URL

Definition of terms

Endpoints

/datasets

Parameters:

/datasets/{dataset_name}

Parameters:

datasets/{dataset_name}/{file_name}

Parameters:

/datasets/history/{dataset_name}

Parameters:

datasets/history/{dataset_name}/{file_name}

Parameters:

Response codes

200 OK

Request example

Response example

Error response codes

403 forbidden

Request example 1

Response example 1

Request example 2

Response example 2

Request example 3

Response example 3

404 Not found

Request example 1

Response example 1

Request example 2

Response example 2

Request example 3

Response example 3

500 Internal server error

Response example

Suggested resolution

Support

Telephone

Email

Address