Exclude Locations from Search

Overview

Description: Any filter parameter, including ones created by the user, can be transformed into an exclusion filter by simply prepending the parameter with _excl_

Endpoint: /v1/custom/locations

Status: Live

Methods: GET

Example use-case: You want to find Imaging Centers in your area, but want to exclude certain facilities known to be expensive, and exclude Hospitals to focus your search on outpatient facilities.

Diving In

Let's do a regular search for Imaging Centers within 5 miles:

cURL

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/locations?location_types=Imaging Center&distance=5' \
  -H 'Authorization: Bearer <Your Token>' \

Lovely! We can see that we get 538 results for this search in the NYC area:

JSON

{
    "parameters": {
        "page": 1,
        "page_size": 25,
        "total_count": 538,
        "sort_by": "distance",
        "distance": 5.0,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "location_types": [
            "Imaging Center"
        ]
    },
    "data": [...]
}

So let's see what happens when we add the following exclusions:

In order to exclude Hospitals, we add: _excl_location_types=Hospital.

In order to exclude specific location UUIDs for facilities known to be expensive, we add: _excl_location_types=904099f2-98a2-487d-9ec9-0fd088409428, 9ad0306a-e998-4575-a96e-3403390f26d7

📘

A B C, easy as 1 2 3! (Except easy as _excl_)

You can add excl to any filter parameter to turn that filter into an exclusion!

Our search will look like:

cURL

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/locations?location_types=Imaging Center&_excl_location_types=Hospital&_excl_location_ids=904099f2-98a2-487d-9ec9-0fd088409428,9ad0306a-e998-4575-a96e-3403390f26d7&distance=5' \
  -H 'Authorization: Bearer <Your Token>' \

This yields us a total of 473 results. Adding thoughtful exclusions can help ensure high-quality search experiences for the user!

JSON

{
    "parameters": {
        "page": 1,
        "page_size": 25,
        "total_count": 473,
        "sort_by": "distance",
        "distance": 5.0,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "_excl_location_ids": [
            "904099f2-98a2-487d-9ec9-0fd088409428",
            "9ad0306a-e998-4575-a96e-3403390f26d7"
        ],
        "location_types": [
            "Imaging Center"
        ],
        "_excl_location_types": [
            "Hospital"
        ]
    },
    "data": [...]
}