Guide to Usage

Understand and get the most out of our API, including links to guides from the data suppliers.



Generalised Request Format

In general all data can be accessed using a URL structured as follows;

nhs-data.uk/api/<key>/<data-group>[/<data-set>]...[[(?|&)<field-name>=<value>[,exact]]...[(?|&)page=<page-num>]]
where...
<key>

...is the mandatory key you will receive buy registering.

<data-group>

...is a mandatory parameter that idenifies the data group you want to search and must be one of the following.

Querying the URL up to and including the <data-group> will return the values available for the <data-set> parameter.

<data-set>

...is an optional parameter that identifies the CSV or XML file from data supplier, and described in their documentation, that you wish to query.

Querying the API with a URL up to and including the <data-set> will return the <field-name> values that can be used in the query portion of the URL.

NOTE: The 'ods' data group supports the special value all that allows searching of all data-sets. Warning, searches on all data may take up to 60 seconds.

NOTE: The 'dmd' data group requires another level whose values can by queried via the API by specifying the URL up to and including the <data-set>.

<field-name>

...is a mandatory parameter in a search query that specified the name of the field in the data set that you wish to search in for the text specified by <value>.

NOTE: The 'ods' data group supports a special value Address that will treat all address fields (Address Line 1 to 5) as a single entity thereby by matching on any part of an address.

<value>

...is a mandatory parameter in a search query that specified the text value you wish to search for in the field specified by the <field-name> parameter.

exact

...is an optional suffix that can follow any <value> delimited with a comma that informs the API that only an exact match should be made.

Omitting this modifier defaults the match functionality to find the <value> within the search text, i.e. a partial match.

page

...is an optional parameter that specifies the <page-num> to retrieve.

Each page returned will contain 100 data elements. To retrieve all data increment <page-num> until less than 100 data elements are returned.

Response Format

Data returned by the API pertaining to a specific query (i.e. not a request that describes the file or collection formats) will be returned in a JSON formated string that contains meta-data. To find out more about JSON click here. This is shown in the example below and demonstrates the following key features;

  • The data is returned in a JSON array as there may be more than one item that matches your search query.
  • Every data item has a unique identifier given by the 'id' element
  • Every data item identifies when the data was created, given by the 'timestamp' element which is in the format YYYYMMDD.
  • Every data item identifies which file or collection the data was found in, given by the 'source' element.
  • Every data item identifies the composite key that matches the search criteria given by 'key' element.
  • The clinical data itself is returned in the 'data' element. This is formatted as JSON but is a string and must therefore be cast to a JSON object, usually by using JSON.parse in JavaScript or the Newtonsoft library in C#. See Get Started for more information and example code.
[
	{
		"id":914738,
		"timestamp":"20150313",
		"source": "egpcur"
		"key": "G0102998"
		"data":"{"Organisation_Code":"G0102998",
			 "Name":"DOC DR",
			 "National_Grouping":"Y98",
			 "Address_Line_1":"SURGERY, GP ROAD",
			 "Address_Line_2":"GP PLACE",
			 "Address_Line_3":"GP TOWN",
			 "Address_Line_4":"GP COUNTY",
			 "Address_Line_5":"",
			 "Postcode":"GP00 0GP",
			 "Open_Date":"19740401",
			 "Close_Date":"",
			 "Organisation_Sub_Type_Code":"P",
			 "Join_Parent_Date":"19740401",
			 "Left_Parent_Date":"19910401"}"
	},
	{
		"id":914739,
		"timestamp":"20150313",
		"source": "egpcur"
		"key": "G0199999"
		"data":"{"Organisation_Code":"G0199999",
			 "Name":"GP DR",
			 "National_Grouping":"Y99",
			 "Address_Line_1":"AN OTHER SURGERY, OTHER ROAD",
			 "Address_Line_2":"OTHER PLACE",
			 "Address_Line_3":"OTHER TOWN",
			 "Address_Line_4":"",
			 "Address_Line_5":"",
			 "Postcode":"DR0 0DR",
			 "Open_Date":"19740401",
			 "Close_Date":"",
			 "Organisation_Sub_Type_Code":"O",
			 "Join_Parent_Date":"19740401",
			 "Left_Parent_Date":"19911231"}"
	}
]
            
Organisation Data Examples (relative to http://nhs-data/api/[key]/)
Download File Spec Document
ods

Get details of all files published by the ODS.

ods/egpcur

Get the specification of the egpcur (current GPs) file, including field names.

ods/egpcur?page=1

Get the first 100 GPs from the egpcur file.

ods/egpcur?Organisation Code=G0102

Get GPs from egpcur with organisational code that contains 'G0102'.

ods/egpcur?Organisation Code=G0105912,exact

Get GPs from egpcur with organisational code that exactly matches 'G0105912'.

ods/egpcur?Organisation Code=G0102&Address Line 1=ROAD

Get GPs from egpcur with organisational code that contains 'G0102' and address line 1 contains the text 'ROAD'.

ods/egpcur?Address=STONY STRATFORD

Get GPs from egpcur that contain STONY STRATFORD in any address field (Address Line 1 to 5).

ods/egpcur?Organisation Code=G&page=2

Get the second 100 GPs from egpcur with organisational code that contains 'G'.

ods/all?...

Using 'all' in the position of data-set will apply the query string all to all ODS data-sets. Warning, searches on all data may take up to 60 seconds.

Dictionary of Medicines and Devices Examples (relative to http://nhs-data/api/[key]/)
Download File Spec Document
dmd

Get details of all available XML file identifiers you can use in in a query.

dmd/vmp

Get all the collections in the Virtual Medicine Products XML file.

dmd/vmp/vmp

Get all the elements that can be used for querying the Virtual Medicine Products collection.

dmd/vmp/vmp?nm=paraffin gauze

Get all Virtual Medicine Products that contain 'paraffin gauze' in their name.

International Classification of Diseases Examples (relative to http://nhs-data/api/[key]/)
Download File Spec Document   Download File Spec Anaylsis Document
icd10

Get details of all available XML file identifiers you can use in a query.

icd10/tocefw

Get all the elements that can be used for querying the Table of Coding Equivalences Forward file.

icd10/tocefw?code=A00

Get all entries that have a code that contains 'A00'.

OPCS4 Classification Examples (relative to http://nhs-data/api/[key]/)
opcs4

Get details of all available XML file identifiers you can use in a query.

opcs4/meta

Get all the elements that can be used for querying the Metadata file.

opcs4/meta?operation_code=A01

Get all entries that have an operation code that contains 'A01'.

Systemic Nomenclature for Medical Clinical Terms (SNOMED CT) Examples (relative to http://nhs-data/api/[key]/)
Download File Spec Document
sct

Get details of all available file identifiers you can use in a query.

sct/description

Get all the fields that can be used for querying the Description data file.

sct/description?term=abnormal chest sounds

Get all entries that have 'term' field that contains 'abnormal chest sounds'.

Data Model and Dictionary Examples (relative to http://nhs-data/api/[key]/)
dd

Get Data Model and Dictionary schema data sets.

dd/cosd

Get the models in the Cancer Outcomes and Services data set.

dd/cosd/BreastContent

Get the types in the BreastContent model of the Cancer Outcomes and Services data set.

dd/cosd/BreastContent?full

Get full details of all the types in the BreastContent model including elements and attributes.

dd/cosd/BreastContent?type=BreastBreastCorePrognosticIndexType

Get full details of the type BreastBreastContentType in the BreastContent model. Partial match not supported.

dd/cosd/BreastContent?schema

Get XML schema of the type BreastBreastContentType in the BreastContent model.