Skip to main content

NHS APIs Service Search API - organisations (version 2)

Information about services provided by NHS organisations listed in the service search on the NHS website.

This API is accessed through HTTP and returns data in a JSON format.

Base URL

All requests to this API should start with the following base URL:

https://api.nhs.uk/service-search

API Version

The API version number can be supplied as a query parameter:

?api-version=2

Authentication and Headers

Your request must include a subscription-key header with a valid subscription key.

Request header keys and values
Header key Header value
subscription-key

Login or register to get an API key to use this API

Endpoints

An endpoint is added to the base URL to create the full request URL. Some APIs have more than 1 type of endpoint you can use.

search-get

Information about services provided by NHS organisations listed in the service search on the NHS website.

Endpoint

GET `/*`

Parameters

Name Type Required Allowed Default Description
search
query
string The text to search for. All searchable fields are searched by default unless searchFields is specified. When searching searchable fields, the search text itself is tokenized, so multiple terms can be separated by white space (for example: search=hello world). To match any term, use * (this can be useful for boolean filter queries). Omitting this parameter has the same effect as setting it to *.
searchMode
query
string any, all any Defaults to any. Specifies whether any or all of the search terms must be matched in order to count the document as a match.
searchFields
query
string The list of comma-separated field names to search for the specified text.
queryType
query
string simple, full simple Defaults to simple. When set to simple, search text is interpreted using a simple query language that allows for symbols such as +, * and "". When the query type is set to full, search text is interpreted using the Lucene query language which allows field-specific and weighted searches.
$skip
query
integer The number of search results to skip.
$top
query
integer The number of search results to retrieve. This defaults to 50.
$count
query
boolean true, false false Optional, defaults to false. Specifies whether to fetch the total count of results. This is the count of all documents that match the search and $filter parameters, ignoring $top and $skip. Setting this value to true may have a performance impact. The count returned is an approximation. If you’d like to get only the count without any documents, you can use $top=0.
$orderby
query
string A list of comma-separated expressions to sort the results by. Each expression can be either a field name or a call to the geo.distance() function. Each expression can be followed by asc to indicate ascending, and desc to indicate descending. The default is ascending order.
$select
query
string A list of comma-separated fields to include in the result set. If unspecified or set to *, all fields marked as retrievable in the schema are included in the projection.
$filter
query
string A structured search expression in standard OData syntax.

Responses

200 - Successful response of filtered services

                          {
  "@odata.context": "https://nhsuksearchproduks.search.windows.net/indexes('organisation-1-1-a-prod')/$metadata#docs(*)",
  "@odata.count": 22573,
  "value": [
    {
      "@search.score": 3.249795,
      "OrganisationID": "10888009",
      "OrganisationName": "London Speech Therapy",
      "OrganisationAliases": [],
      "OrganisationTypeID": "GDOS",
      "OrganisationType": "Generic Directory of Services",
      "OrganisationStatus": "Visible",
      "IsPimsManaged": false,
      "PIMSCode": null,
      "NACSCode": null,
      "LocalAuthorityCode": null,
      "SummaryText": null,
      "URL": "www.netmums.com/local/l/london-speech-therapy",
      "Address1": "127 Harley Street",
      "Address2": "London",
      "Address3": null,
      "City": "London",
      "County": "London",
      "Latitude": 51.5220832824707,
      "Longitude": -0.14864355325698853,
      "OrganisationSubType": "Generic Directory of Services",
      "LastUpdatedDate": "2020-03-10T14:12:13.273Z",
      "Postcode": "W1G 6AZ",
      "Geocode": {
        "type": "Point",
        "coordinates": [
          -0.148644,
          51.5221
        ],
        "crs": {
          "type": "name",
          "properties": {
            "name": "EPSG:4326"
          }
        }
      },
      "CCG": [],
      "RelatedIAPTCCGs": [],
      "Trusts": [],
      "CCGLocalAuthority": [],
      "ServicesOffered": [],
      "ServicesProvided": [],
      "ServiceCodesProvided": [],
      "ServicesProvidedConditions": [],
      "OrgTypeConditions": [],
      "OpeningTimes": null,
      "Contacts": "[{\"OrganisationContactType\":\"Primary\",\"OrganisationContactAvailabilityType\":\"Office hours\",\"OrganisationContactMethodType\":\"Telephone\",\"OrganisationContactValue\":\"020 3475 2189\"},{\"OrganisationContactType\":\"Primary\",\"OrganisationContactAvailabilityType\":\"Office hours\",\"OrganisationContactMethodType\":\"Website\",\"OrganisationContactValue\":\"www.netmums.com\\/local\\/l\\/london-speech-therapy\"}]",
      "VenueType": null,
      "Metrics": null,
      "GSD": "[{\"ElementTitle\":\"About\",\"ElementText\":\"Netmums is an online community for parents providing information and support to make family life easier and happier for all.   \\nNetmums is completely FREE to use and it offers: \\n• Local boards where you can find childcare, buy and sell nearly new items and post notices for other parents who live near you\\n• Many thousand of listings from toddler groups to day nurseries and from indoor playcentres to what is on events, all in your local area and many with comments from other parents.\\n• Mnline support for parents from professionals and from other parents.\\n• Local meet a mum\\n• A friendly supportive national chat forum \\n• Information on anything relating to parenting and family life from part time work to recipe ideas for feeding the family \\nFor this and more go to www.netmums.com\"},{\"ElementTitle\":\"Further information\",\"ElementText\":\"This entry has been provided by Netmums. For further information regarding this service please contact netmum using the website link provided\"}]",
      "OpeningTimesV2": []
    }
  ],
  "tracking": "<img style='border: 0; width: 1px; height: 1px;' alt='' src='https://nhsdigital.d3.sc.omtrdc.net/b/ss/nhsuk-prod/1/JS-2.9.0-L8UK/654321?c27=56dda0792399060e5876b61c&c28=/indexes/organisation-1-1-a-prod/docs/?search=london&searchMode=any&queryType=simple&$skip=0&$top=1&$count=true&api-version=1&c29=ServiceSearch&c75=web&events=event23'/>"
}
                        

search-post

Information about services provided by NHS organisations listed in the service search on the NHS website.

Endpoint

POST `/*`

Responses

200 -

                          
                        

search-post by postcode or place name

Information about services provided by NHS organisations listed in the service search on the NHS website filtered by postcode or place name.

Endpoint

POST `/search-postcode-or-place`

Parameters

Name Type Required Allowed Default Description
search
query
string true Search a postcode or place name
latitude
query
string Search a location based on latitude
longitude
query
string Search a location based on longitude
body
body
To generate a response body visit http://api-bridge.azurewebsites.net/servicesearchguide. You can also read Microsoft's search documentation at https://docs.microsoft.com/en-us/rest/api/searchservice/search-documents

Responses

200 - This has multiple responses. If the result has a list of services then it will show those, if however the result has multiple place names it will list options to choose from. Eg. Gillingham, Kent and Gillingham, Dorset.

                          {
  "value": [
    {
      "text": "Manchester, North West, M2",
      "url": "https://api.nhs.uk/multiple/searchbypostcode?search=manchester&latitude=53.4789416719026&longitude=-2.24527799829848"
    },
    {
      "text": "New Manchester, North West, M28",
      "url": "https://api.nhs.uk/multiple/searchbypostcode?search=manchester&latitude=53.5142654482367&longitude=-2.41990039231912"
    }
  ]
}
                        

404 - Returns an error message which can be displayed to users.

                          {
  "errorName": "We can't find 'unknown'",
  "errorText": "If the place you searched for is in England, you could: check your spelling and try again or try a different place name.",
  "errorHTML": "<h1>We can't find 'unknown'</h1><p>If the place you searched for is in England, you could:</p><ul><li>check your spelling and try again</li><li>try a different place name</li></ul>"
}
                        

Attribution

Any syndicated content must incorporate the following attribution (credit) to the NHS website:

Content supplied by the NHS website logo

The logo should be clearly visible and in line with the associated content on every web page that contains the syndicated content. You should also link this logo to the relevant page on the NHS website that the content has been supplied from. This URL is supplied as part of the feed under author:

"author": {
  "url": "https://www.nhs.uk",
  "logo": "https://www.nhs.uk/nhscwebservices/documents/logo1.jpg",
  "email": "nhswebsite.servicedesk@nhs.net",
  "@type": "Organization",
  "name": "NHS website"
}

If you are displaying NHS syndicated content in a context where a functional link back to the article on the NHS website is not possible then you should use the following attribution (credit):

From www.nhs.uk

Caching

Caching all content supplied through our API is recommended where possible. Unless otherwise notified by the syndication team, you should refresh cached content at least once every 7 days. If instructed to refresh cached our content, you must do so immediately.

Information:

Certain topics on the NHS website need to be refreshed more frequently than every 7 days. Find out about content not covered by our standard terms and conditions.

Usage caps

When using a trial subscription, you will only be able to run 10 calls/minute up to a maximum of 1,000 calls per month. A full subscription caps usage at 4,000 calls per hour. You are not to call the APIs over 4,000 times in any one-hour period, unless you have notified the syndication team in advance and they have confirmed in writing that you can do so.

Standard licence terms

By using the NHS website syndicated content, you agree to be bound by the standard licence terms.

Your contact details

You must provide accurate contact details that must be kept up to date while you are using our content. Failure to keep contact details updated is a breach of our licence terms and may result in your subscription being disabled. You can check your details on your profile.

Information:

Help and support

If you need help using any of our APIs , please email the NHS website service desk at nhswebsite.servicedesk@nhs.net.