ALISS

Introduction to ALISS🔗︎ 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 ALISS (A Local Information System for Scotland), which itself is also offered to the public (see https://www.aliss.org) . ALISS is a service designed to help citizens find help and support close to you when you need it most. ALISS is maintained and published by the Health and Social Care Alliance Scotland (the ALLIANCE) and is funded by the Scottish Government.

Mydex consumes the ALISS API from the upstream source.

The upstream ALISS API lists all individual services. Within each service record there may exist a set of 'location', 'organisation' and 'category' data (thereby, each service record holds duplicate information for these subsets of data).

Mydex's MRD API 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 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:

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.

Getting ALISS data by ID🔗︎ click to copy

Making a basic request🔗︎ click to copy

Where you know the id of the specific service/s you want to return, it is possible to make a request in the format:

aliss/get-services/{service-ids}

Where service-ids is a list of one or more service ids delineated by a comma “,”. For example we can pass 3 service-ids like so:

aliss/get-services/2d29f1ab-d617-45d7-83b5-b755dd6658a4,25525a5e-a405-4ddb-bf50-3a32fe005151,259ea6be-6861-4e45-82ee-5a3ff6eeb6a1

Adding query parameters🔗︎ click to copy

The following additional options are available to add to your request:

Order the results🔗︎ click to copy

The following query parameters can be added to your request:

“order” can be set to either ASC or DESC, and “order_by” to either ‘id’ (the id of the service) or ‘name’ (the name of the service). If no query parameters are set, the default is to order by ASC on ‘id’.

An example request might look like:

aliss/get-services/2d29f1ab-d617-45d7-83b5-b755dd6658a4,25525a5e-a405-4ddb-bf50-3a32fe005151?order=ASC&order_by=name

Choose the format🔗︎ click to copy

You can choose to get your response in either ‘JSON’ or ‘XML’ format. Again, this can be added as a query param like so “?format=XML”

An example request might look like:

aliss/get-services/2d29f1ab-d617-45d7-83b5-b755dd6658a4,25525a5e-a405-4ddb-bf50-3a32fe005151?format=XML

Order the results and choose the format🔗︎ click to copy

If you want to order the results and choose the format, simply concatenate the required query params as shown above.

An example request might look like:

aliss/get-services/2d29f1ab-d617-45d7-83b5-b755dd6658a4,25525a5e-a405-4ddb-bf50-3a32fe005151?order=ASC&order_by=name&format=XML

Searching the ALISS data🔗︎ click to copy

Please Note: Mydex also offers a Cross-Service search capability for unified search results across the different MRD services you are subscribed to. Click here to find out more.

Below is an example of a search payload:

aliss/get-services/search?categories=physical-activity

Understanding the allowed fields search parameters🔗︎ click to copy

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

Search by location🔗︎ click to copy

Below is an example of a search with a partial postcode

/aliss/get-services/search?postcode=G1

Below is an example of a search with a full postcode

/aliss/get-services/search?postcode=FK2 9EE

Search by category🔗︎ click to copy

Below is an example of a search by category

/aliss/get-services/search?categories=health-social-care-services

Search by service area code🔗︎ click to copy

Below is an example of a search by service area codes

/aliss/get-services/search?service-areas=S12000020

Filters🔗︎ click to copy

Below is an example of a search request using filters

/aliss/get-services/search?service-areas=S12000020&filters[locations][0][operator]==&filters[locations][0][field]=postal_code&filters[locations][0][value]=AB32 6FT&filters[locations][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 location, categories, service, organisation and service area. However, there are specific fields for each of those datasets that the user can filter by - see table below.

It 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
Location name, locality, postal_code
Categories slug
Services name
Service Areas name, type
Organisation name

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 [categories]

[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] Do we want to search for an exact value or for something similar or for various values? This will be the option operator to search valueThe only valid operators are IN, LIKE and = IN
[field] By which field we want to filter by. See all valid fields. slug
[value] The value to use to filter the results. children-families,rights-representation
[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.

Filters examples🔗︎ click to copy

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

/aliss/get-services/search?service-areas=S12000020&filters[locations][0][operator]==&filters[locations][0][field]=postal&filters[locations][0][value]=AB32 6FT&filters[locations][0][condition]=AND&filters[categories][1][operator]==&filters[categories][1][field]=name&filters[categories][1][value]=Health %26 Social Care Services&filters[categories][1][condition]=

aliss/get-services/search?service-areas=S12000020&filters[categories][0][operator]=IN&filters[categories][0][field]=slug&filters[categories][0][value]=children-families,rights-representation&filters[categories][0][condition]=

/aliss/get-services/search?categories=physical-activity&filters[locations][0][field]=postal_code&filters[locations][0][operator]==&filters[locations][0][value]=G73 3LW&filters[locations][0][condition]=OR&filters[locations][1][field]=locality&filters[locations][1][operator]==&filters[locations][1][value]=Blantyre&filters[locations][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:

/aliss/get-services/search?service-areas=S12000020&filters[locations][0][operator]=LIKE&filters[locations][0][field]=postal_code&filters[locations][0][value]=AB32&filters[locations][0][condition]=AND&filters[categories][1][operator]==&filters[categories][1][field]=slug&filters[categories][1][value]=activity&filters[categories][1][condition]=&order_by=services-name&order=DESC&format=xml

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=services-name ` where services 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 `.

Examples🔗︎ click to copy

Example API Request🔗︎ click to copy

    https://api-mrd.mydex.org/aliss/get-services/search?categories=physical-activity
    &filters[service_areas][0][field]=name
    &filters[service_areas][0][operator]==
    &filters[service_areas][0][value]=Dumfries and Galloway
    &filters[service_areas][0][condition]=OR
    &filters[service_areas][1][field]=name
    &filters[service_areas][1][operator]==
    &filters[service_areas][1][value]=Argyll and Bute
    &filters[service_areas][1][condition]=
    &order_by=services-name

See below response examples, showing only the first service 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": "040e47b5-0d9f-4883-8c29-c271ad3f80b7",
        "name": "Branching Out Argyll",
        "description": "Branching Out Argyll runs innovative programmes of woodland based activities for people with poor mental health. \r\nWith Argyll and the Isles being a large location and all the central areas of population being geographically far apart, loneliness can be a major risk of cognitive decline.\r\n\r\nBy getting people back to nature, Branching Out helps to tackle the problems people face with anxiety, depression and isolation. People overcome their problems together with support and teamwork out in the woods. Whether it’s cooking food on a camp fire, building a shelter, walking, tai-chi or mindfulness.",
        "url": "http://www.act-now.org.uk/en/what-we-do/233-branching-out",
        "email": "branchingout@act-now.org.uk",
        "slug": "branching-out-argyll-0",
        "last_updated": "2018-12-06T10:00:08.82",
        "phone": "01546 602755",
        "categories": [
            {
                "name": "Mental Health",
                "slug": "mental-health"
            },
            {
                "name": "Physical Activity",
                "slug": "physical-activity"
            },
            {
                "name": "Outdoor Pursuits",
                "slug": "outdoor-pursuits"
            },
            {
                "name": "Conditions",
                "slug": "conditions"
            },
            {
                "name": "Health & Social Care Services",
                "slug": "health-social-care-services"
            },
            {
                "name": "Support Network",
                "slug": "support-network"
            },
            {
                "name": "Activity",
                "slug": "activity"
            }
        ],
        "service_areas": [
            {
                "code": "S12000035",
                "name": "Argyll and Bute",
                "type": "Local Authority"
            }
        ],
        "locations": [
            {
                "formatted_address": "1 Kilmory Industrial Estate, Lochgilphead, PA31 8RR",
                "name": "",
                "description": null,
                "street_address": "1 Kilmory Industrial Estate",
                "locality": "Lochgilphead",
                "region": null,
                "state": null,
                "postal_code": "PA31 8RR",
                "country": "GB",
                "latitude": "56.0267332",
                "longitude": "-5.4256996",
                "id": "d9286637-4b6b-4eca-99d1-77deb25f2973"
            }
        ],
        "organisation": [
            {
                "id": "c9d78550-77f8-496b-8a0e-6bd6b7f8475f",
                "name": "Argyll and the Isles Coast and Countryside Trust",
                "slug": "argyll-and-the-isles-coast-and-countryside-trust-0",
                "is_claimed": "0"
            }
        ]
    },
    {
        "id": "c13d575e-a929-4e06-bdcf-1bbbe67042aa",
        "name": "Buddy dog",
        "description": "Our buddy dogs bring a new friend into the lives of children with sight loss. By helping to develop their self-confidence, improve relationships and build a greater sense of trust, these dogs can have a hugely positive effect on your child’s wellbeing.\r\nA buddy dog is:\r\n•\tA friendly, well-behaved pet dog.\r\n•\tA great way to show your child the responsibility of caring for a dog.\r\n•\tAble to help your child increase their physical activity, build confidence, create better relationships with others, and develop a sense of fun and trust.\r\n•\tLooked after and paid for by your family, including vets’ bills and insurance, but is owned by Guide Dogs.\r\nA buddy dog is not a guide dog, so it cannot be used as a mobility aid for sighted assistance. As wi",
        "url": "https://www.guidedogs.org.uk/getting-support/help-for-children-and-families/buddy-dogs-for-children/",
        "email": "information@guidedogs.org.uk",……

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"?>
    <Services>
        <Service>
            <id>040e47b5-0d9f-4883-8c29-c271ad3f80b7</id>
            <name>Branching Out Argyll</name>
            <description>Branching Out Argyll runs innovative programmes of woodland based activities for people with poor mental health. &#xD;
            With Argyll and the Isles being a large location and all the central areas of population being
            geographically far apart, loneliness can be a major risk of cognitive decline.&#xD;
            By getting people back to nature, Branching Out helps to tackle the problems people face with anxiety,
            depression and isolation. People overcome their problems together with support and teamwork out in the
            woods. Whether it&#x2019;s cooking food on a camp fire, building a shelter, walking, tai-chi or mindfulness.
            </description>
            <url>http://www.act-now.org.uk/en/what-we-do/233-branching-out</url>
            <email>branchingout@act-now.org.uk</email>
            <slug>branching-out-argyll-0</slug>
            <last_updated>2018-12-06T10:00:08.82</last_updated>
            <phone>01546 602755</phone>
            <categories>
                <name>Mental Health</name>
                <slug>mental-health</slug>
                <name>Physical Activity</name>
                <slug>physical-activity</slug>
                <name>Outdoor Pursuits</name>
                <slug>outdoor-pursuits</slug>
                <name>Conditions</name>
                <slug>conditions</slug>
                <name>Health &amp; Social Care Services</name>
                <slug>health-social-care-services</slug>
                <name>Support Network</name>
                <slug>support-network</slug>
                <name>Activity</name>
                <slug>activity</slug>
            </categories>
            <service_areas>
                <node>
                    <code>S12000035</code>
                    <name>Argyll and Bute</name>
                    <type>Local Authority</type>
                </node>
            </service_areas>
            <locations>
                <node>
                    <formatted_address>1 Kilmory Industrial Estate, Lochgilphead, PA31 8RR</formatted_address>
                    <name/>
                    <description/>
                    <street_address>1 Kilmory Industrial Estate</street_address>
                    <locality>Lochgilphead</locality>
                    <region/>
                    <state/>
                    <postal_code>PA31 8RR</postal_code>
                    <country>GB</country>
                    <latitude>56.0267332</latitude>
                    <longitude>-5.4256996</longitude>
                    <id>d9286637-4b6b-4eca-99d1-77deb25f2973</id>
                </node>
            </locations>
            <organisation>
                <id>c9d78550-77f8-496b-8a0e-6bd6b7f8475f</id>
                <name>Argyll and the Isles Coast and Countryside Trust</name>
                <slug>argyll-and-the-isles-coast-and-countryside-trust-0</slug>
                <is_claimed>0</is_claimed>
            </organisation>
            </Service>
            <Service>
                <id>c13d575e-a929-4e06-bdcf-1bbbe67042aa</id>
                <name>Buddy dog</name>
                <description>Our bud………..
                &#xD;
                By getting people back to nature, Branching Out helps to tackle the problems people face with anxiety,
                depression and isolation. People overcome their problems together with support and teamwork out in the
                woods. Whether it&#x2019;s cooking food on a camp fire, building a shelter, walking, tai-chi or mindfulness.
            </description>
            <url>http://www.act-now.org.uk/en/what-we-do/233-branching-out</url>
            <email>branchingout@act-now.org.uk</email>
            <slug>branching-out-argyll-0</slug>
            <last_updated>2018-12-06T10:00:08.82</last_updated>
            <phone>01546 602755</phone>
            <categories>
                <name>Mental Health</name>
                <slug>mental-health</slug>
                <name>Physical Activity</name>
                <slug>physical-activity</slug>
                <name>Outdoor Pursuits</name>
                <slug>outdoor-pursuits</slug>
                <name>Conditions</name>
                <slug>conditions</slug>
                <name>Health &amp; Social Care Services</name>
                <slug>health-social-care-services</slug>
                <name>Support Network</name>
                <slug>support-network</slug>
                <name>Activity</name>
                <slug>activity</slug>
            </categories>
            <service_areas>
                <node>
                    <code>S12000035</code>
                    <name>Argyll and Bute</name>
                    <type>Local Authority</type>
                </node>
            </service_areas>
            <locations>
                <node>
                    <formatted_address>1 Kilmory Industrial Estate, Lochgilphead, PA31 8RR</formatted_address>
                    <name/>
                    <description/>
                    <street_address>1 Kilmory Industrial Estate</street_address>
                    <locality>Lochgilphead</locality>
                    <region/>
                    <state/>
                    <postal_code>PA31 8RR</postal_code>
                    <country>GB</country>
                    <latitude>56.0267332</latitude>
                    <longitude>-5.4256996</longitude>
                    <id>d9286637-4b6b-4eca-99d1-77deb25f2973</id>
                </node>
            </locations>
            <organisation>
                <id>c9d78550-77f8-496b-8a0e-6bd6b7f8475f</id>
                <name>Argyll and the Isles Coast and Countryside Trust</name>
                <slug>argyll-and-the-isles-coast-and-countryside-trust-0</slug>
                <is_claimed>0</is_claimed>
            </organisation>
        </Service>
        <Service>
            <id>c13d575e-a929-4e06-bdcf-1bbbe67042aa</id>
            <name>Buddy dog</name>
            <description>Our bud………..