What happened to the GPPractices XML API and where is the official replacement?

General enquiries
, ,
1

We use the GP Practices postcode lookup API in an app we have built. It has been dormant for a couple of years and during the restart and testing I’ve noticed our GP search feature has broken due to the following API endpoint not existing anymore:

https://api.nhs.uk/data/gppractices/postcode/[postcode]?distance=15&page=1

I’ve checked all the documentation and the closest thing I’ve found to this is the following endpoint:
https://directory.spineservices.nhs.uk/ORD/2-0-0/organisations?PrimaryRoleId=RO177&PostCode=[postcode]

This however does not give me the following data with the response that the previous endpoint did:

  • Full address
  • Telephone
  • Latitude
  • Longitude
  • Distance from search

I also cannot choose a distance in miles to search on this endpoint.

Has this endpoint just moved? Or has its replacement not actually replaced all of its features?

2

Have you looked at Service Search API - organisations (version 2) - NHS website developer portal

I think that allows distance searches. I would expect GP Organisations to be also classed as services.

3

That seems to be the best replacement Kevin thanks!

Note about the service search api:

  • Mixture of query params and body params for POST requests (not sure this is best practice, and it feels slightly messy)
  • Slight issues in the format of the body params can give false “not found” errors for places that do exist (no actual validation of the request configuration) Example below:

The following request provides the subsequent error message:

POST /service-search/search-postcode-or-place/?search=LE169QL&api-version=2 HTTP/1.1
subscription-key:---
Content-Type: application/json; charset=utf-8
Host: api.nhs.uk
Connection: close
User-Agent: Paw/3.3.6 (Macintosh; OS X/12.1.0) GCDHTTPRequest
Content-Length: 63

{"latitude":"52.6336159190942","longitude":"-1.13346203516866"}



{
  "optionalErrorName": "We can't find 'LE169QL'",
  "optionalErrorText": "If the place you searched for is in England, you could: check your spelling and try again or try a different place name.",
  "optionalErrorHTML": "<h1>We can't find 'LE169QL'</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>"
}

The error message is extremely misleading and it is very difficult to see what the actual issue with the request is. Removing the “latitude” and “longitude” parameters from this request makes it return a 200 response with correct data.

The documentation isn’t very informative about this and it caused me quite a few issues. The above example isn’t the exact use case that led me to encounter this problem, its just the clearest way to explain the issue.