Food Hygiene Rating Scheme API (Version 2)
The Food Hygiene Rating Scheme Application Programming Interface (FHRS API) provides free programmatic access to the Food Standards Agency Rating Data for England, Scotland, Wales and Northern Ireland.
Developers can leverage FSA data to provide their own services and websites, allowing you to build and develop custom solutions that are consistent with the data being held and displayed by the FSA. As a developer you get access to the same data and the majority of the same functionality that is used to deliver the Food Hygiene Rating Scheme
Getting started
Other that calling the available endpoints, there are no registration requirements for developers before they can start using the Food Standards Agency data. No sign-up process, API keys, or login details are required at this time to use the service. Note: If this situation changes, then this documentation will be updated and a new version of the FHRS API will be issued.
Some important information
API Versions
The FHRS API is a versioned API, meaning that multiple versions of the API can exist in parallel and the developer is free to select which version they wish to use. To select the appropriate version, all calls to the API must include the version required in the header (an example is shown below). The FSA will maintain at least one previous depreciated version of the API to allow developers to migrate their code steadily, however the FSA make no guarantees that older versions of the API will continue to work when they fall more than one version behind the current API. Please note: If a version is not supplied in the header, calls to FHRS API endpoints will not return data.
To select a version number add the following to the header request:
Languages
The FHRS API is able to return requests in both English and Welsh languages. To select the appropriate language, calls to the API should include the language required in the header (an example is shown below). Please note that the default is for English returned if no header value is supplied. Please note that due to data translations, the same results may not be returned for a search in different languages.
To select Welsh return values add the following to the header request:
Data lookup
A number of endpoints are provided within the FHRS API to allow developers to request relevant lookup data which can be used in other endpoints to search for establishment records. Most endpoints provide the ability for a developer to request 'basic' or 'detailed' information, depending on their requirement.
Search
The Establishments endpoint provides the ability for developers to search the ratings data using a number of search terms, filters as well as spatial information. The developer can also request the paging and sorting used for the return data to reduce the volume of data required per call. For specific details of the usage of the search please refer to the 'Establishments' section below.
Technical prerequisites
This guidance assumes that you are familiar with Web Services and XML (Both structure and syntax). For refreshers or overviews of these topics w3schools offer guides describing both of these topics in detail. Whilst the FHRS API is programming language agnostic, any examples are currently only be provided in C#, for examples of Web Services interactions with other languages, please refer to your specific language reference guides.
FHRS API Endpoint Index (Version 2)
BusinessTypes
| API | Description |
|---|---|
| GET BusinessTypes/{pageNumber}/{pageSize} |
Returns details of all business types, page parameters allow for page number and size specification. |
| GET BusinessTypes/basic/{pageNumber}/{pageSize} |
Returns a basic list of business types, details can be retrieved by calling countries/{id}, page parameters allow for page number and size specification. |
| GET BusinessTypes/basic |
Returns a basic list of business types, results are unbound. |
| GET BusinessTypes |
Returns details of all business types, results are unbound. |
| GET BusinessTypes/{id} |
Returns details of a single business type, selected by Id. |
Regions
| API | Description |
|---|---|
| GET Regions/{pageNumber}/{pageSize} |
Returns details of all regions, page parameters allow for page number and size specification. |
| GET Regions/basic/{pageNumber}/{pageSize} |
Returns a basic list of regions, details can be retrieved by calling regions{id}, page parameters allow for page number and size specification. |
| GET Regions/basic |
Returns a basic list of regions, details can be retrieved by calling regions{id}. |
| GET Regions |
Returns details of all regions, results are unbound. |
| GET Regions/{id} |
Returns details of a single region, selected by Id. |
Authorities
| API | Description |
|---|---|
| GET Authorities/{pageNumber}/{pageSize} |
Returns details of all authorities, page parameters allow for page number and size specification. |
| GET Authorities/basic/{pageNumber}/{pageSize} |
Returns a basic list of authorities (id/name), details can be retrieved by calling authorities/{id}, page parameters allow for page number and size specification. |
| GET Authorities/basic |
Returns a basic list of authorities (id/name), details can be retrieved by calling authorities/{id}, results are unbound. |
| GET Authorities |
Returns details of all authorities, results are unbound. |
| GET Authorities/{id} |
Returns details of a single authority, selected by Id. |
Countries
| API | Description |
|---|---|
| GET Countries/{pageNumber}/{pageSize} |
Returns details of all countries, page parameters allow for page number and size specification. |
| GET Countries/basic/{pageNumber}/{pageSize} |
Returns a basic list of countries, details can be retrieved by calling countries/{id}, page parameters allow for page number and size specification. |
| GET Countries/basic |
Returns a basic list of countries, results are unbound. |
| GET Countries |
Returns details of all countries, results are unbound. |
| GET Countries/{id} |
Returns details of a single country, selected by Id. |
Establishments
| API | Description |
|---|---|
| GET Establishments/basic/{pageNumber}/{pageSize} |
Returns a basic list of establishments (id/name), details can be retrieved by calling establishments/{id}, page parameters allow for page number and size specification. |
| GET Establishments/basic |
Returns a basic list of establishments, details can be retrieved by calling establishments/{id}. |
| GET Establishments/{id} |
Returns a details of a single establishment, selected by Id. |
| GET Establishments?name={name}&address={address}&longitude={longitude}&latitude={latitude}&maxDistanceLimit={maxDistanceLimit}&businessTypeId={businessTypeId}&schemeTypeKey={schemeTypeKey}&ratingKey={ratingKey}&ratingOperatorKey={ratingOperatorKey}&localAuthorityId={localAuthorityId}&countryId={countryId}&sortOptionKey={sortOptionKey}&pageNumber={pageNumber}&pageSize={pageSize} |
Returns a collection of establishment details, based on provided search parameters. All search parameters are optional. |
Ratings
| API | Description |
|---|---|
| GET Ratings |
Returns details of all ratings, results are unbound. |
SchemeTypes
| API | Description |
|---|---|
| GET SchemeTypes |
Returns details of all SchemeTypes, results are unbound. |
ScoreDescriptors
| API | Description |
|---|---|
| GET ScoreDescriptors?establishmentId={establishmentId} |
Returns details of all scoreDescriptor, results are unbound. |
SortOptions
| API | Description |
|---|---|
| GET SortOptions |
Returns details of all SortOptions, results are unbound. |