Search services

This endpoint allows you to search the whole list of services for matching results.

This is a partial implementation of this Open Referral UK endpoint.

Request

/services

The following query parameters are accepted:

Parameter	Description	Example
taxonomies=	Only returns services in one or more of the supplied taxonomy slugs, separated with a comma. Provide multiple strict independent groups of taxonomies by repeating the parameter: a result must match at least one value from each independent group to be shown.	taxonomies=5-to-7,8-to-11&taxonomy=things-to-do
needs=	Only returns services in one or more of the supplied SEND need slugs, separated with a comma. Provide multiple strict independent groups of needs by repeating the parameter.	needs=autism,hearing
only=	Further refine the results with special strict filters. Provide multiple values by repeating the parameter. Only the value of free is supported right now.	only=free
min_age= and max_age=	Find services that cater for the given age range	min_age=4
keywords=	Find services with a match in the name or description. Sorts by relevance.	keywords=evening gym
location=	Provide a string that can be geocoded into a location within the UK. Will be geocoded and used to sort results by increasing distance from that point. Overrides any existing sort order.	location=Aylesbury
lat= and lng=	As above, but skip the geocoding step.	lng=-0.78206&lat=51.612687
page=	Move through the results	page=2
per_page=	Modify the number of results per page. Defaults to 20 if not given.	per_page=10

Some filters are strict, in that if you provide more than one, services will need to match all the supplied filters to be returned, rather than the normal behaviour, which is one or more.

Example response

Status: 200 OK

{
    "page": 1,
    "size": 1,
    "totalPages": 1,
    "totalElements": 1,
    "content": [
        {
            "id": 3556,
            "name": "My Great Service",
            "description": "",
            "url": "",
            "min_age": null,
            "max_age": null,
            "bccn_member": false,
            "current_vacancies": false,
            "pick_up_drop_off_service": false,
            "needs_referral": false,
            "free": true,
            "created_at": "2020-06-29T18:38:13.351Z",
            "updated_at": "2020-06-30T15:49:50.800Z",
            "locations": [
                {
                    "id": 2858,
                    "name": "",
                    "address_1": "10 Town Street",
                    "city": "Aylesbury",
                    "state_province": "Buckinghamshire",
                    "postal_code": "HP20 1UA",
                    "country": "GB",
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            -0.835807,
                            51.940749
                        ]
                    },
                    "accessibilities": [
                        {
                            "name": "British sign language"
                        },
                        {
                            "name": "Hoist"
                        }
                    ]
                }
            ],
            "contacts": [],
            "organisation": {
                "id": 2678,
                "name": null,
                "description": null,
                "email": null,
                "url": null
            },
            "taxonomies": [
                {
                    "id": 10,
                    "name": "Things to do",
                    "slug": "things-to-do"
                },
                {
                    "id": 136,
                    "name": "Outdoor",
                    "slug": "outdoor"
                }
            ],
            "regular_schedules": [],
            "links": [],
            "cost_options": [],
            "send_needs": [],
            "local_offer": null,
            "distance_away": null,
            "score": 0,
        }
    ]
}

Score

If you provide keywords, results will include a score value that represents how well they match your search terms.

Distance away

If you provide any geographic sort parameters to the API, this will show the straight-line distance away in miles. Otherwise, it will be null.

If the service has more than one location, the distance to the nearest one will be shown.

Locations

Locations have a geometry key which will be a GeoJSON object. At the moment these are all points, but some may eventually represent geographic coverage areas as the dataset evolves.

Locations can also be masked in the interests of privacy. A masked location will have less accurate information:

• The street address will be null
• Only the first part of the postcode will be visible
• Latitude and longitude values will be rounded to 2 decimal places, reducing their accuracy.
• The key mask_exact_address will be true, so you can handle this case differently in your application.

Local offer

For services that are part of the Buckinghamshire local offer, this is an object with details of the SEND provision. Otherwise it is null.