Health A to Z

Introduction🔗︎ click to copy

Mydex Data Services CIC provides an API known as the 'Master Reference Data Services' or MRD. This API provides access to a variety of non-personal, general purpose datasets that may be of use when integrating with the rest of the Mydex platform.

One of these services or datasets is the HAZ (NHS A to Z Health Conditions), which itself is also offered to the public (see https://www.nhs.uk/conditions/) . HAZ is a service designed to help citizens find help and support close to you when you need it most.

Mydex hosts its own copy of Health Conditions A to Z and also consumes the HAZ API from the upstream source to pull in other information if needed.

Mydex's MRD Service hosts the data and adds mapping tables that split out locations, service areas, organisations and categories into separate tables. This allows more complex joining of services to those other attributes, or the ability to search by location, category or service area to find services (rather than having to search for the services first). Mydex's MRD API also allows more complex filtering and combinations in the search, along with sorting options.

To find out how to authenticate to the MRD to access this service, please visit the MRD Authentication instructions.

This guide explains:

How to construct different search requests to Mydex's MRD API to obtain different types of results from the Health Conditions A to Z datasets.

If you encounter issues either getting authenticated to or using the MRD API, please contact support@mydex.org . Our team is ready and always happy to help you with any issues.

Searching the HAZ data🔗︎ click to copy

Below is an example of a search payload:

haz/get-health-condition/search?health-condition=type 2 diabetes

Understanding the allowed fields search parameters🔗︎ click to copy

The field parameter describes the main search made by the user. There are two options for search that the user can select, it can be one of the below:

Health condition
Description

Search by description🔗︎ click to copy

Below is an example of a search for a health condition description. This will return all health conditions which have a description of ‘rash’.

/haz/get-health-condition/search?description=rash

Filters🔗︎ click to copy

Below is an example of a search request using filters

/haz/get-health-condition/search?health-condition=cancer&filters[conditions][0][value]=diabetes&filters[conditions][0][operator]=LIKE&filters[conditions][0][field]=name&filters[conditions][0][condition]=

Understanding the allowed fields for filtering🔗︎ click to copy

The fields parameters describe the allowed filters by which the user can filter the main search results. The user can filter by name, description.

Is worth noting that if the user queries our endpoint with an invalid filter field we have validation in place to only allow valid fields, so it will throw an error.

Dataset	Valid fields
conditions	name, description

Understanding the structure for filtering🔗︎ click to copy

The filters are passed as an array with the dataset name to filter by and the operator, field, value (to use as the filter value) and the condition.

The structure must be the following:

filters[dataset][index][option]=value

[dataset] e.g [conditions]

[index] e.g [0], it starts from 0 for the first filter and must increment by 1 if using more than one filter. Here is an example taken from the filters examples section.

[option] e.g [field], There are four [option] parameters that must be present when filtering the data, these are the operator, field, value and condition. See all options needed below.

Understanding the options🔗︎ click to copy

Parameter	Description	Example
[operator]	When searching for multiple health conditions set the operator to LIKE	LIKE
[field]	By which field we want to filter by. See all valid fields.	name
[value]	The value to use to filter the results.	diabetes
[condition]	If we want to filter by more than one dataset field we can include here AND or OR (only these two are valid conditions). If we are only using one filter then it must be declared but left empty.	AND

Filters examples🔗︎ click to copy

Below are some examples of the types of filtering that can be done with the search results.

Apply a filter to search for multiple health conditions by name

/haz/get-health-condition/search?health-condition=Cancer&filters[conditions][0][value]=Diabetes&filters[conditions][0][operator]=LIKE&filters[conditions][0][field]=name&filters[conditions][0][condition]=OR&filters[conditions][1][value]=ASTHMA&filters[conditions][1][operator]=LIKE&filters[conditions][1][field]=name&filters[conditions][1][condition]

Filter options🔗︎ click to copy

The data can be ordered, sorted and returned in a specific format if the user specifies this.

Below is an example with all the filter options:

haz/get-health-condition/search?description=cough&format=xml&order=DESC&order_by=conditions-name

Order🔗︎ click to copy

To specify the order add ` order=DESC ` to the request. If the order parameter is not present the default value will be ASC = ascending.

Order by (Sort)🔗︎ click to copy

To order the data by a specific field, the name of the dataset and the valid field need to be added to the request, e.g. ` order_by=conditions-name ` where conditions is the dataset and name is the field to order by.

Return format🔗︎ click to copy

The data can be returned in a JSON and XML format. The default return format is JSON if no format is specified. To specify the return format, add to the request ` format=xml `.

Extracting additional information🔗︎ click to copy

As part of our MRD Health A to Z service we are able to pull in additional information for specific health conditions once selected.

By adding api to the endpoint this will return the additional data that is available for the selected health condition. The parameter must be an exact match to the the health condition.

Below is an example of a search payload:

haz/get-health-condition/search/api?health-condition=whooping cough

The field parameter describes the main search made by the user. The difference here is that the health condition cannot be a general term, it must be an exact match. For example a search for ‘cough’ will not return a result as there is no health condition for ‘cough’. However a search for ‘whooping cough’ will return a correct response.

Examples🔗︎ click to copy

Example API Request🔗︎ click to copy

    https://api-mrd.mydex.org/haz/get-health-condition/search?health-condition=cancer
    &filters[conditions][0][value]=diabetes
    &filters[conditions][0][operator]=LIKE
    &filters[conditions][0][field]=name
    &filters[conditions][0][condition]=
    &order_by=conditions-name

See below response examples, showing only the first few health conditions returned (as data can be quite long to insert the full example). This will provide an idea of the structure of the data in the response.

Example Response JSON🔗︎ click to copy

[
    {
        "id":"12",
        "name":"Anal cancer",
        "description":"Anal cancer is a rare type of cancer that affects the anus. Get information and advice about symptoms, causes and treatments.",
        "url":"https://api.nhs.uk/conditions/anal-cancer/",
        "articleStatus":"published",
        "dateModified":"2022-07-12T15:04:44+00:00",
        "datePublished":"2017-10-17T16:08:41+00:00",
        "lastReviewed":"2021-03-08T01:00:00+00:00",
        "reviewDue":"2024-03-08T01:00:00+00:00"
    },
    {
        "id":"297",
        "name":"Benign brain tumour (non-cancerous)",
        "description":"Information about benign (non-cancerous) brain tumours, including types of tumour, when to see a GP, causes, treatment and recovery.",
        "url":"https://api.nhs.uk/conditions/benign-brain-tumour/",
        "articleStatus":"published",
        "dateModified":"2021-11-18T15:36:51+00:00",
        "datePublished":"2017-10-20T14:02:09+00:00",
        "lastReviewed":"2020-04-21T00:00:00+00:00",
        "reviewDue":"2023-04-21T00:00:00+00:00"
    },
    {
        "id":"298",
        "name":"Bile duct cancer (cholangiocarcinoma)",
        "description":"Understand more about bile duct cancer, its symptoms, when to get medical help, testing and diagnosis, treatment and where to find help and support.",
        "url":"https://api.nhs.uk/conditions/bile-duct-cancer/",
        "articleStatus":"published",
        "dateModified":"2022-07-12T15:07:12+00:00",
        "datePublished":"2017-10-20T13:18:18+00:00",
        "lastReviewed":"2020-05-05T14:42:00+00:00",
        "reviewDue":"2023-05-05T14:42:00+00:00"
    },

Example Response XML🔗︎ click to copy

Adding &format=xml to the above example API request, will see the data returned as XML:

<?xml version="1.0"?>
<Conditions>
    <Condition>
        <id>12</id>
        <name>Anal cancer</name>
        <description>Anal cancer is a rare type of cancer that affects the anus. Get information and advice aboutsymptoms, causes and treatments.</description>
        <url>https://api.nhs.uk/conditions/anal-cancer/</url>
        <articleStatus>published</articleStatus>
        <dateModified>2022-07-12T15:04:44+00:00</dateModified>
        <datePublished>2017-10-17T16:08:41+00:00</datePublished>
        <lastReviewed>2021-03-08T01:00:00+00:00</lastReviewed>
        <reviewDue>2024-03-08T01:00:00+00:00</reviewDue>
    </Condition>
    <Condition>
        <id>297</id
        ><name>Benign brain tumour (non-cancerous)</name>
        <description>Information about benign (non-cancerous) brain tumours, including types of tumour, when to see aGP, causes, treatment and recovery.</description>
        <url>https://api.nhs.uk/conditions/benign-brain-tumour/</url>
        <articleStatus>published</articleStatus>
        <dateModified>2021-11-18T15:36:51+00:00</dateModified><datePublished>2017-10-20T14:02:09+00:00
        </datePublished>
        <lastReviewed>2020-04-21T00:00:00+00:00</lastReviewed>
        <reviewDue>2023-04-21T00:00:00+00:00</reviewDue>
    </Condition>
    <Condition>
        <id>298</id>
        <name>Bile duct cancer (cholangiocarcinoma)</name>
        <description>Understand more about bile duct cancer, its symptoms, when to get medical help, testing anddiagnosis, treatment and where to find help and support.</description>
        <url>https://api.nhs.uk/conditions/bile-duct-cancer/</url>
        <articleStatus>published</articleStatus>
        <dateModified>2022-07-12T15:07:12+00:00</dateModified>
        <datePublished>2017-10-20T13:18:18+00:00</datePublished>
        <lastReviewed>2020-05-05T14:42:00+00:00</lastReviewed>
        <reviewDue>2023-05-05T14:42:00+00:00</reviewDue>
    </Condition>

Example Response for additional information🔗︎ click to copy