GuidesAPI ReferenceTry Ribbon!
Guides

Using Weighted Custom Filters

Suggest Edits

Note, this is a premium feature and may not be enabled in your API index. Please reach out to Ribbon Support ([email protected]) for additional information on accessing Weighted Custom Filters!

Overview

You may want more control over what order your results come back in. Custom filters affect what results are shown, but not what order they appear in. Boost filters affect the order results come back in, but by default, all matches are considered equally.

You can exert greater control over the order of your results by assigning scores to each match, which tells us how highly to weight that match. You do this by appending a score to your filter values in a format such as <score=10>. Your results will then be returned sorted first by weight - highest score first - and then by our regular sort orders. Let's see this in action.


Filtering On Location Confidence

You may want to do a provider search where providers with high-confidence locations are returned first. You could use our built-in min_location_confidence parameter with a value of 3, which would get you back only providers with locations of confidence 3or higher.

Let's take a look at this in action:

https://api.ribbonhealth.com/v1/custom/providers?page_size=5&min_location_confidence=3&fields=npi%2Cdistance%2Clocations.uuid%2Clocations

{'data': [{'distance': 0.04,
           'locations': [{'confidence': 3.0,
                          'uuid': '59a31a8a-0ddf-4dbc-b072-4314c3378917'}],
           'npi': '1699817080'},
          {'distance': 0.04,
           'locations': [{'confidence': 4.0,
                          'uuid': '44bcec92-8f95-4ba8-851d-5a35fa006a06'},
                         {'confidence': 4.0,
                          'uuid': '768e6994-df58-416f-ac62-ae92718f9d55'}],
           'npi': '1649298019'},
          {'distance': 0.05,
           'locations': [{'confidence': 4.0,
                          'uuid': 'b50a1a75-2fc1-4e18-9568-92715c39628f'},
                         {'confidence': 3.0,
                          'uuid': '851617c5-4573-4e8b-a21c-1681941e5c24'}],
           'npi': '1467511634'},
          {'distance': 0.05,
           'locations': [{'confidence': 3.0,
                          'uuid': '85d65359-e82c-43a0-8984-b2b23a231659'}],
           'npi': '1316025422'},
          {'distance': 0.05,
           'locations': [{'confidence': 3.0,
                          'uuid': '1b1b1caf-fd16-4c63-8663-2fef03d1d78f'}],
           'npi': '1285660225'}],
 'parameters': {...}}

As you can see here, the providers themselves and the locations within them are not ordered by confidence - results with a location of confidence of 3 appear before results with a location of confidence of 5. The results all match the filter of locations.confidence being 3, 4, or 5, but are only sorted by the default sort order - distance.

Solving This With A Custom Filter

Weighted custom filters cannot be used with filters doing numeric comparisons such as greater than and less than. Our built-in min_location_confidence parameter is equivalent to a custom filter with a filter_type of greater_than, and as such cannot be used to solve this problem.

Instead, let's create a custom filter with the following properties:

{
    'parameter': 'location_confidence',
    'field': 'locations.confidence',
    'value_type': 'integer',
    'filter_type': 'equals_any',
}

First, let's confirm that we get back the same results as using min_location_confidence:

https://api.ribbonhealth.com/v1/custom/providers?page_size=5&location_confidence=3%2C4%2C5&fields=npi%2Cdistance%2Clocations.uuid%2Clocations

{'data': [{'distance': 0.04,
           'locations': [{'confidence': 3.0,
                          'uuid': '59a31a8a-0ddf-4dbc-b072-4314c3378917'}],
           'npi': '1699817080'},
          {'distance': 0.04,
           'locations': [{'confidence': 4.0,
                          'uuid': '44bcec92-8f95-4ba8-851d-5a35fa006a06'},
                         {'confidence': 4.0,
                          'uuid': '768e6994-df58-416f-ac62-ae92718f9d55'}],
           'npi': '1649298019'},
          {'distance': 0.05,
           'locations': [{'confidence': 4.0,
                          'uuid': 'b50a1a75-2fc1-4e18-9568-92715c39628f'},
                         {'confidence': 3.0,
                          'uuid': '851617c5-4573-4e8b-a21c-1681941e5c24'}],
           'npi': '1467511634'},
          {'distance': 0.05,
           'locations': [{'confidence': 3.0,
                          'uuid': '85d65359-e82c-43a0-8984-b2b23a231659'}],
           'npi': '1316025422'},
          {'distance': 0.05,
           'locations': [{'confidence': 3.0,
                          'uuid': '1b1b1caf-fd16-4c63-8663-2fef03d1d78f'}],
           'npi': '1285660225'}],
 'parameters': {...}

Using location_confidence=3,4,5 does indeed get the same results back as when we used min_location_confidence=3. Great! So how do we apply weighted filtering to this?

Filter scores are added to filter values by appending <score={number}> to the end, substituting in an actual number. These numbers tell us how highly to weight each result. Results are sorted first by weight/score, then by our default sort orders. In our case, let's score each confidence with a numeric value equal to the confidence score. We therefore want to set location_confidence to be equal to 3<score=3>,4<score=4>,5<score=5>:

https://api.ribbonhealth.com/v1/custom/providers?page_size=5&location_confidence=3%3Cscore%3D3%3E%2C4%3Cscore%3D4%3E%2C5%3Cscore%3D5%3E&fields=npi%2Cdistance%2Clocations.uuid%2Clocations

{'data': [{'distance': 0.31,
           'locations': [{'confidence': 5.0,
                          'uuid': 'f099c988-5737-48e0-98f8-78121ad9bba2'},
                         {'confidence': 5.0,
                          'uuid': '620f5a2a-1b2c-4087-8bbe-68d8a7993b20'}],
           'npi': '1437178332'},
          {'distance': 2.69,
           'locations': [{'confidence': 5.0,
                          'uuid': 'f0ccfeb3-8bdb-4889-92cb-6b3bd20684e7'},
                         {'confidence': 5.0,
                          'uuid': '7137d859-9e6b-48b6-b881-ebbc609b13cb'}],
           'npi': '1790762839'},
          {'distance': 0.04,
           'locations': [{'confidence': 4.0,
                          'uuid': '44bcec92-8f95-4ba8-851d-5a35fa006a06'},
                         {'confidence': 4.0,
                          'uuid': '768e6994-df58-416f-ac62-ae92718f9d55'}],
           'npi': '1649298019'},
          {'distance': 0.05,
           'locations': [{'confidence': 4.0,
                          'uuid': 'b50a1a75-2fc1-4e18-9568-92715c39628f'},
                         {'confidence': 3.0,
                          'uuid': '851617c5-4573-4e8b-a21c-1681941e5c24'}],
           'npi': '1467511634'},
          {'distance': 0.08,
           'locations': [{'confidence': 4.0,
                          'uuid': '055ef864-b892-452f-926a-cce4ef66d34b'},
                         {'confidence': 3.0,
                          'uuid': 'a0032885-28c8-489f-921d-c338e1bc6fd4'}],
           'npi': '1427056837'}],
 'parameters': {...}

Now, we get back:

  • All providers whose highest location confidence is 5, sorted by distance.
  • All providers whose highest location confidence is 4, sorted by distance.
  • All providers whose highest location confidence is 3, sorted by distance.

Additionally, since we are targeting locations, the locations array is sorted according to our weights as well.

📘

Note

locations is a special case. If you boost or use weighted filters on any other list field, the list will not be sorted accordingly. This only works with locations.

For example, you could use weighted filters with our built-in insurance_ids field to move providers who accept specific insurance plan UUIDs to the front of the providers list, but we would not resort the insurances list for those providers to move the matched insurances to the front.


Weighted Filters Work With Boost Filters Too

The example above was using a custom filter rather than a boost filter. Weighted filtering works with boost filters as well in order to exert greater control on the order.

For example, imagine if our location_confidence custom filter had instead been a boost filter with this configuration:

{
    'parameter': 'location_confidence',
    'field': 'locations.confidence',
    'value_type': 'list',
    'filter_type': 'boost',
}

The largest difference between this and our custom filter is that locations with lower confidences would still have been shown (i.e., not filtered out) but at the end.

If we made a request using this boost filter as location_confidence=3,4,5, the resulting sort order would have been:

  • All providers whose highest location confidence is 3, 4, or 5, sorted by distance.
  • All providers whose highest location confidence is 1 or 2, sorted by distance.

Similar to our custom filter example, this isn't what we wanted. We wanted to boost confidence 5 higher than 4, and 4 higher than 3. The exact same solution works here - weighted filter.

If we instead set location_confidence to 3<score=3>,4<score=4>,5<score=5> again, we will get back:

  • All providers whose highest location confidence is 5, sorted by distance.
  • All providers whose highest location confidence is 4, sorted by distance.
  • All providers whose highest location confidence is 3, sorted by distance.
  • All providers whose highest location confidence is 1 or 2, sorted by distance.

When using weighted filters, you should decide between a boost filter and a custom filter based on whether you want to receive results that do not match your filter values at all. Boost filters will still return those, custom filters will not.

Updated 8 months ago