APIs
This site provides curated APIs from datasets that from the National Information Infrastructure on data.gov.uk
APIs are grouped into themes, such as Health, or Transport and provide endpoints for different NII datasets
Using the APIs
All APIs are available via the /api urls described below. Requests should always be GET requests and should set the accept header to application/json
Responses are returned as JSON except for those that support a format argument, which will allow data to be downloaded as CSV
Metadata
Metadata is available for the various services within each theme, and can be accessed at //data.gov.uk/data/api/service. The results from this call with be an object where each key is the theme name, and for each value there will a list of service endpoints that can be used.
{
"transport": [
{
"name": "planned_road_works",
"description": "Information on planned roadworks carried out on the Highways Agency network",
"dataset": "highways_agency_planned_roadworks"
},
{
"name": "anonymised_mot_test",
"description": "Anonymised MOT results",
"dataset": "anonymised_mot_test"
}
],
"health": [
{
"name": "hospitals",
"description": "Location of NHS Hospitals",
"dataset": "hospitals_"
},
{
"name": "clinics",
"description": "Location of NHS Clinics",
"dataset": "clinics"
},
]
}
The list of service endpoints for a given theme is also available, for example //data.gov.uk/data/api/service/health
Pre-defined queries
Within each theme, most services have a list of pre-defined queries (such as those for the health theme) that can be used and completed by the user. This functionality can be replicated by using the filter api below.
It is possible however, for each theme and service, to get a list of the known distinct fields. These fields have been identified as containing a limited set of values and are therefore available for use. They can be accessed at //data.gov.uk/data/api/service/health/distinct. It is also possible to get the distinct values for a single service, so social_care_locations within health would be //data.gov.uk/data/api/service/health/distinct/social_care_locations.
Filters
Filtered queries are available by specifying the field and value in the query string of a request to /data/api/service/:theme/:service. For example to find a clinic with the organisation_code of NCP21 a request should be made to //data.gov.uk/data/api/health/clinics?organisation_code=NCP21
{
"success":true,
"result": [
{
"website":"",
"sub_type":"UNKNOWN",
"postcode":"SO19 9GH",
"phone":"",
"partial_postcode":"SO19",
"organisation_type":"Clinic",
"organisation_status":"Visible",
"organisation_name":"Weston Lane Surgery",
"organisation_id":"59370",
"organisation_code":"NCP21",
"longitude":"-1.3711330890655518",
"latitude":"50.88800048828125",
"is_pims_managed":"False",
"fax":"",
"email":"",
"county":"Hampshire",
"city":"Southampton",
"address3":"",
"address2":"",
"address1":"Weston Lane"
}
]
}
Multiple filters can be applied through the use of the & operator. For example, to return all planned road works on the M1 where the local_authority is "Leicestershire / Northamptonshire" a request should be made to //data.gov.uk/data/api/service/transport/planned_road_works?road=M1&local_authority=Leicestershire / Northamptonshire
Information on what fields are available can be found in the SQL tab, although an API may be made available to access the schema for a service directly in future.
Using SQL
It is possible to query the database behind each service directly by sending a request to /api/health/sql with your SQL query in a parameter called query. For example a request to //data.gov.uk/data/api/service/health/sql?query=SELECT * FROM clinics LIMIT 2 will generate the following response
{
"success": true,
"result": [
{
"website": "",
"sub_type": "UNKNOWN",
"postcode": "HR2 7RL",
"phone": "",
"partial_postcode": "HR2",
"organisation_type": "Clinic",
"organisation_status": "Visible",
"organisation_name": "Ross Road Health Clinic and Child Development Centre",
"organisation_id": "41",
"organisation_code": "5CN17",
"longitude": "-2.7209534645080566",
"latitude": "52.046333312988281",
"is_pims_managed": "True",
"fax": "",
"email": "",
"county": "Hereford",
"city": "",
"address3": "",
"address2": "",
"address1": "Ross Road"
},
{
"website": "http://www.covwarkpt.nhs.uk/pages/city-of-coventry-health-centre.aspx",
"sub_type": "UNKNOWN",
"postcode": "CV1 4FS",
"phone": "024 7696 1311",
"partial_postcode": "CV1",
"organisation_type": "Clinic",
"organisation_status": "Visible",
"organisation_name": "City of Coventry Health Centre",
"organisation_id": "568",
"organisation_code": "5MD81",
"longitude": "-1.5041433572769165",
"latitude": "52.415061950683594",
"is_pims_managed": "True",
"fax": "",
"email": "enquiries@covwarkpt.nhs.uk",
"county": "West Midlands",
"city": "Coventry",
"address3": "",
"address2": "Stoney Stanton Road",
"address1": "City of Coventry Health Centre"
}
]
}
Should a query generate a response, the output will be slightly different as the success value will be false and an error message will be returned. For example trying select something from somewhere:
{
"success": false,
"error": "relation \"somewhere\" does not exist"
}