Boost Filters

For most of our standard filters, providers or locations that don't match our search query won't appear in the returned results. But what if these non-matching providers or locations are still relevant to the user? What if we wanted results that match our search query to appear at the top, while still keeping less-relevant results that don't match our filter near the bottom? The answer is: Boost Filters.

Boost Filters are a type of filter_type which "boosts" providers or locations that match our search query to the top of our results while keeping non-matching yet potentially relevant options near the bottom of our results.

📘

Boost Filters works for both Providers and Locations!

Though the following example shows how to create and utilize a Boost Filter for providers, the same process can also be applied to locations by using the /v1/custom/locations/filters endpoint!

Let's look at an example. Let's say we want to Boost Filter by the languages field in a provider record. To create this Boost Filter, we simply create a new custom directory filter with "filter_type": "boost"

curl -X POST \
  https://api.ribbonhealth.com/v1/custom/providers/filters \
  -H 'Authorization: Bearer <Your Token>' \
  -d '{
  "filter_type": "boost",
  "value_type": "string",
  "parameter": "language_spoken",
  "field": "languages"
}'

Congrats! You've created your first Boost Filter. Now let's say we ideally want to find a Spanish-speaking provider, but can also see a provider that doesn't speak Spanish if necessary. Essentially, we want to boost Spanish-speaking providers to the top of our results. We would conduct a GET call to v1/custom/providers?language_spoken=Spanish and get the following results:

{
    "parameters": {
        "page": 1,
        "page_size": 25,
        "sort_by": "distance",
        "distance": 1,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9903544
        },
        "boost_filters": {
            "language_spoken": "spanish"
        }
        "address": "33 Irving Pl, New York, NY 10003, USA"
    },
    "data": [
        {
            "first_name": "Gene",
            "languages": ["spanish"],
            "distance": 0.72,
            ...
        },
        {
            "first_name": "Naila",
            "languages": ["spanish", "english"],
            "distance": 0.87,
            ...
        },
        {
            "first_name": "Stephan",
            "languages": ["english"],
            "distance": 0.04,
            ...
        },
        {
            "first_name": "Stephanie",
            "languages": ["english"],
            "distance": 0.06,
            ...
        },
    ]
}

Notice how Gene and Naila show up at the top of our results, since they are close to our location and match our language_spoken=Spanish Boost Filter. However, we still include Stephan and Stephanie in our results because they are close to our location, even though they don't necessarily match our Boost Filter. That's the magic of Boost Filters!

Our Boost Filter also includes automatic type validation. Let's say we create the Boost Filter shown below, with a boolean as the value_type:

curl -X POST \
  https://api.ribbonhealth.com/v1/custom/providers/filters \
  -H 'Authorization: Bearer <Your Token>' \
  -d '{
  "filter_type": "boost",
  "value_type": "boolean",
  "parameter": "is_pcp",
  "field": "is_pcp"
}'

If we try to execute a GET request such as v1/custom/providers?is_pcp=Ribbon, we will get an error because the string data type of our filter value "Ribbon" doesn't match the boolean type of our filter:

{
    "error": {
        "status": 400,
        "code": "bad_request",
        "message": "Error: Data type of one of your query parameters does not match the data type 'BOOLEAN' of your custom boost filter"
    }
}

❗️

Limitations with Boost Filters

Currently, the following configurations will not work with Boost Filters:
• Searching with a Boost Filter by multiple values, such as a GET request to: /v1/custom/providers?language_spoken=English,Spanish
• Using our _excl_ keyword in front of a Boost Filter parameter
• Creating a Boost Filter with the following data types: float, list
• Creating a Boost Filter based on a field that is within a list of objects, such as ‘locations.confidence’