API Documentation
Introduction
Welcome to the ALISS API docs. You can use our API to search for health and wellbeing services in Scotland. ALISS offers the following public API endpoints:
- Services
- Lists
- Import
- Organisations
A Swagger UI page is available, providing a machine-readable resource listing for the API.
Attribution and licensing
ALISS allows the use of data under a Creative Commons (CC BY 4.0) licence. For more information see ALISS Terms and Conditions.
ALISS, contains data from a variety of sources, including:
- National Statistics data © Crown copyright and database right 2018 (Open Government Licence v3.0)
- The Scottish Charity Register (Office of the Scottish Charity Register) shared under the Open Government Licence (v2.0)
- Scottish Postcode Directory (National Records of Scotland) shared under the Open Government Licence (v3.0)
- Contributions by ALISS users
Services
The service search feature is the core of ALISS. Search returns services on ALISS filtered optionally by geography, keywords accessibility features, community groups or categories.
Services can be delivered at a specific location, or they can be delivered across a whole area or areas. Locations are specific to the organisations that run the services, whereas areas of delivery are selected from a pre-defined list. You can request the list of possible areas from the service-areas endpoint.
HTTP Request
GET https://api.aliss.org/v5/services/
You can request an HTML formatted version of the result with your browser: https://api.aliss.org/v5/services/?postcode=G2 4AA
|
Parameter |
Required |
Default |
Description |
Data type |
|
postcode |
False |
None |
The postcode that you wish to find services close to |
String |
|
q |
False |
None |
This can contain keywords with which to do a full text search of the services |
String |
|
category |
False |
None |
The category slugs that you wish to filter the search by |
String |
|
location_type |
False |
None |
The location type of the resource, either 'local' or 'national', default searches everything |
String |
|
radius |
False |
5000 |
The radius from the postcode that you wish the search to cover, in metres |
Integer |
|
page_size |
False |
10 |
The number of results in a page (max. 100) |
Integer |
|
sort |
False |
None |
The order required for results. Options are sort-last-reviewed, sort-a-z, sort-recently-added, sort-relevance, sort-distance. |
String |
|
community_groups |
False |
None |
The community groups slugs that you wish to filter the search by. |
String |
|
accessibility_features |
False |
None |
The accessibility feature slugs that you wish to filter the search by. |
String |
|
source |
False |
None |
If you wish to identify yourself as a user of the API, you can use this field. Does not affect the results of the call. |
String |
|
service_areas |
False |
None |
The service area slugs that you wish to filter the search by. If present, this overrides any postcode and radius search. |
String |
|
stopIpTracking |
False |
False |
By default, ALISS records the IP address of API users. Set this to True to prevent the collection of your IP address |
Boolean |
Filter by categories
GET https://api.aliss.org/v5/services/?category=money-advice&postcode=G2 4AA
You can filter by category by using the category query parameter and passing in a category slug.
Filter by location type
GET https://api.aliss.org/v5/services/?location_type=local&postcode=G2 4AA
You can filter by location type by using the location type query parameter and passing in either 'local' or 'national'.
Response structure
|
Key |
Description |
|
meta |
metadata associated with the result |
|
count |
number of results returned in all pages of the request |
|
next |
url to next page |
|
previous |
url to previous page |
|
data |
collection of service objects (see below) |
Service object
|
Key |
Description |
|
id |
UUID for the service |
|
name |
name of the service |
|
description |
free text description of the service |
|
description_formatted |
html version of the description of the service |
|
url |
url to a site describing the service |
|
referral_url |
url to a page where referrals can be made to the service |
|
phone |
contact telephone number for the service |
|
|
contact email address for the service |
|
|
url to the Facebook page for the service |
|
|
url to the X/Twitter page for the service |
|
|
url to the Instagram page for the service |
|
summary |
free text summary of the service (max 200 characters) |
|
categories |
collection of category objects associated with the service including a human readable name and slug |
|
accessibility_features |
collection of accessibility features associated with the service including a human readable name and slug |
|
community_groups |
collection of the associated with the service including a human readable name and slug |
|
service_areas |
collection of service area objects associated with the service, a full list of possible areas can be requested from the service areas endpoint |
|
media_gallery |
collection of objects containing urls for media uploaded for the service (images or videos) |
|
organisation |
object containing data on the organisation providing the service |
|
slug |
the unique part of the aliss_url for the service |
|
aliss_url |
human friendly url to the service entry on aliss.org |
|
permalink |
url to the service entry on aliss.org |
|
is_claimed |
boolean indicating whether the service has been claimed |
|
is_deprioritised |
boolean indication whether the service has been reviewed in the last 12 months |
|
last_updated |
timestamp (ISO 8601) of when the service entry was last edited |
|
last_reviewed |
timestamp (ISO 8601) of when the service entry was last reviewed |
|
locations |
collection of location objects associated with the service |
|
location_score |
score is determined by whether the service has a address, region or both |
Lists
There are a number of endpoints which provide lists as output. They all have the following parameters:
|
Parameter |
Required |
Default |
Description |
Data type |
|
source |
False |
None |
If you wish to identify yourself as a user of the API, you can use this field. Does not affect the results of the call. |
String |
|
stopIpTracking |
False |
False |
By default, ALISS records the IP address of API users. Set this to True to prevent the collection of your IP address |
Boolean |
The main ‘list’ endpoints are as follows:
https://api.aliss.org/v5/categories
https://api.aliss.org/v5/service-areas
https://api.aliss.org/v5/community-groups
https://api.aliss.org/v5/accessibility-features
Import
https://api.aliss.org/v5/import
This is endpoint returns all services in json format. The available parameters are as follows:
|
Parameter |
Required |
Default |
Description |
Data type |
|
source |
False |
None |
If you wish to identify yourself as a user of the API, you can use this field. Does not affect the results of the call. |
String |
|
stopIpTracking |
False |
False |
By default, ALISS records the IP address of API users. Set this to True to prevent the collection of your IP address |
Boolean |
|
page |
False |
1 |
The import endpoint returns all services, 20 entries per page. Use this parameter to request a specific page. Usually used in conjunction with the ‘next’ and ‘prev’ responses referred to above. |
Integer |
Organisations
https://api.aliss.org/v5/organisations
This is a list endpoint for organisations which can be filtered using the ‘searchTerm’ parameter.
|
Parameter |
Required |
Default |
Description |
Data type |
|
source |
False |
None |
If you wish to identify yourself as a user of the API, you can use this field. Does not affect the results of the call. |
String |
|
stopIpTracking |
False |
False |
By default, ALISS records the IP address of API users. Set this to True to prevent the collection of your IP address |
Boolean |
|
page |
False |
1 |
The import endpoint returns all services, 20 entries per page. Use this parameter to request a specific page. Usually used in conjunction with the ‘next’ and ‘prev’ responses referred to above. |
Integer |
|
searchTerm |
False |
None |
This can contain keywords with which to do a full text search of the |
string |
End of page