Guide

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 or an empty list.

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.
  • id - This element contains a unique identifier for each data item
  • timestamp - This element contains the date that the data was created in the format YYYYMMDD. NOTE: Historic data is returned so changes over time can be tracked, therefore the timestamp can be used to identify the latest data.
  • source - This element identifies which file or collection the data was found in.
  • key - This element identifies the composite key that matched the search criteria.
  • data - This element contains the clinical data itself. 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.

dmd/ampp/price_info?appid=1100000&appid=1327911000001107,exact&appid=1200000

Get price info for medical product packs where appid contains 1100000 or 1200000 or exactly matches 1327911000001108.

dmd/ampp/price_info?appid=1100000&appid=1327911000001107,exact&appid=1200000&price_prev=2820

Get price info for medical product packs where appid contains 1100000 or 1200000 or exactly matches 1327911000001108 and price_prev contains 2820.

dmd/ampp/price_info?appid=1100000&appid=1327911000001107,exact&appid=1200000&page=2

Get the seond page of prices info for medical product packs where appid contains 1100000 or 1200000 or exactly matches 1327911000001108.

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.