Library

Browse and search developer information

Parameters

Search Parameter Examples

 

PostCode

Where an organisation address contains a postcode, the ODS ORD API is able to use this to locate an organisation reference data record. There are 2 variations of search available to locate an ODS record using a postcode, neither of which are case sensitive.

Searching using a partial postcode

Where a partial organisation postcode is available e.g. LS1, it is possible to search using this value only:-

This will return summary information for one or more organisations which have an exact match to ‘LS1’ on the first segment of their postcode. The search will not return records for organisations with LS10 or LS13 etc. as the first segment of their postcode.

Searching using an exact match

Where a full postcode for an organisation is known, this can be used to search organisation reference data.  To search for an exact postcode the following search should be executed:-

This will return summary information for all organisations where the postcode is exactly LS1 4BT. Search expressions are not case sensitive and will return appropriate results with or without a space between the 2 elements of the postcode (i.e. LS14BT and LS1 4BT).

 

Record Status

An organisation record can have a status of Active or Inactive (not case sensitive).

This will return summary information for all organisation records with a status of Inactive.

 

PrimaryRoleID and NonPrimaryRoleID

All organisations within organisation reference data have a primary role which denotes their core function. Primary Roles are listed within the OrgRefData Data Item Catalogue which is available on the ODS XML Supporting Products webpage within the ‘ancilliary’ zip file. Organisations may also have one or more non primary roles if they carry out additional functions. Non Primary Roles are also listed within the Data Item Catalogue.  Each Role has a Role ID and a Role Name, for example:-

It is the RoleID that must be specified within the API search parameter.  When used in a search the role ID is not case sensitive.

The above will return summary information for one or more organisations where the Primary Role ID specified (RO101) is stated within the organisation record (i.e. it will return all records flagged as ‘Care Home Sites’).

The above will return summary information for one or more organisations where a Non Primary Role ID of RO76 (GP Practice Prescribing Cost Centre) is stated within the organisation record. In this example, GP Practices have a primary role of RO177 Prescribing Cost Centre (along with Out of Hours, Walk in Centres etc), but to filter this down to only include GP Practice settings then a non primary role of RO76 must be specified.

 

Record Class

Health and Social Care Organisation Reference Data currently employs two top-level Record Classes:

  • Health and Social Care Organisation (HSCOrg) = RC1
  • Health and Social Care Organisation Site (HSCSite) = RC2

The above search returns summary information for one or more organisations where the Record Class matches the string provided, in this example, HSCOrg (RC1). Valid options are RC1 for HSCOrg records and RC2 for HSCSite records. When used in a search the record class codes are not case sensitive.

 

Summary Record Format

{"Organisations": [
{
"Name": "116 ST GREGORY'S CRESCENT",
"OrgId": "G82032001",
"Status": "Active",
"OrgRecordClass": "RC2",
"PostCode": "DA12 4JW",
"LastChangeDate": "2018-04-18",
"PrimaryRoleId": "RO96",
"PrimaryRoleDescription": "BRANCH SURGERY",
"OrgLink": "https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations/G82032001"
} ]
}

All parameters listed above can be combined to filter for records, e.g.

The above search returns summary information for one or more organisations where the OrgRecordClass and LastChangeDate match.

 

Data Format

Data is returned as JSON by default however the data can be returned as XML using the _format parameter

  • valid options are xml or json (lowercase only).  json does not need to be specified.

The above search returns data as xml for a single organisation.

The above search returns summary information for one or more organisations with the summary formatted as xml.

 

Default Number of Records Returned (Limit)

Results are limited to 20 records by default.  This can be extended to a maximum of 1,000 using the Limit parameter.

 

Offset

Used to offset the start point of the result set, by the value specified. The argument can range from 1-<x-total-count>. See also HTTP Headers page for further information regarding ‘Offset’.