ALISS
Introduction to ALISS
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:
- How to construct different search requests to Mydex's MRD API to obtain different types of results from the ALISS dataset.
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 ALISS data
Below is an example of a search payload:
aliss/get-services/search?categories=physical-activity
Understanding the allowed fields search parameters
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:
- Location
- Category
- Service area (code)
Search by location
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
Below is an example of a search by category
/aliss/get-services/search?categories=health-social-care-services
Search by service area code
Below is an example of a search by service area codes
/aliss/get-services/search?service-areas=S12000020
Filters
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
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 |
| Service | name |
| Service Areas | name, type |
| Organisation | name |
Understanding the structure for filtering
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
| 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
Below are some examples of the types of filtering that can be done with the search results.
-
Apply a filter WHERE something equals something AND WHERE something else equals something
/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]=
-
Apply a filter WHERE there are multiple values IN the same field that could be valid
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]=
-
Apply a filter WHERE and OR for one field and apply an AND statement to another field to deliver the return I want
/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
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
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)
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
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
Example API Request
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
[
{
"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
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. 
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.
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’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 & 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………..

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’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 & 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………..