Create New Location Search Filters

Overview

Description: The listings and search endpoint allows you to quickly pull locations based on important search criteria.

Endpoint: /v1/custom/locations/filters

Status: Live

Methods: GET, POST

Example use-case: This endpoint allows you to create new filters to be used when searching for locations in the /v1/custom/locations endpoint. Let's say you add a new field to a bunch of locations that match your use case, for instance c_section_rate. You could make this field searchable so that your search through v1/custom/locations when you pass through a certain parameter that specifies a maximum threshold.

Diving In

There are 4 fields we need to specify in order to create a new filter:

parameter is what will be used when you want to pass your filter through /v1/custom/locations
field is the field in the location object that will be used to filter results
value_type is either "string", "float", "integer", "boolean", or "list". This tell us what kind of value the field is.
filter_type is one of either "less_than", "greater_than", "equals", or "contains"

To create a filter for locations who have a C-section rate less than a certain threshold, we have:

{
  "filter_type": "less_than",
  "value_type": "float",
  "parameter": "max_c_section_rate",
  "field": "c_section_rate"
}

So, before we go through the process of creating this filter, let's break this down. What does this mean?

If we want to only show locations in our search that have a c_section_rate below 15.5, we would be able to do so by searching v1/custom/locations?max_c_section_rate=15.5. Awesome!

Let's create this filter:

curl -X POST \
  https://api.ribbonhealth.com/v1/custom/locations/filters \
  -H 'Authorization: Bearer <Your Token>' \
  -d '{
  "filter_type": "less_than",
  "value_type": "float",
  "parameter": "max_c_section_rate",
  "field": "c_section_rate"
}'

Awesome. We can now get a look of all of the filters we've created at doing a GET request at v1/custom/locations/filters:

{
  "data": [{
  "uuid": "9da04268-65e4-4422-a095-98208695b8b9",
  "filter_type": "less_than",
  "value_type": "float",
  "parameter": "max_c_section_rate",
  "field": "c_section_rate"
}]
}

Let's say we updated just one location object with a field named c_section_rate set to 8.3. Then, if we do a GET call to v1/custom/locations?max_c_section_rate=2 we get no results:

{
    "parameters": {
        "page": 1,
        "page_size": 10,
        "sort_by": "distance",
        "distance": 10,
        "geo": {
            "latitude": 40.7358633,
            "longitude": -73.9910835
        },
        "address": "Union Square, New York, NY 10003, USA",
        "max_c_section_rate": 2
    },
    "data": [ ]
}

Since all locations do not have this field, and the one location we did update was set to 8.3, it's not surprising we got no results!

So lets move up our call up to 10: v1/custom/locations?max_c_section_rate=10. Now, when we do a GET, we actually get the one location we updated!

{
    "parameters": {
        "page": 1,
        "page_size": 10,
        "sort_by": "distance",
        "distance": 10,
        "geo": {
            "latitude": 40.7358633,
            "longitude": -73.9910835
        },
        "address": "Union Square, New York, NY 10003, USA",
        "max_c_section_rate": 2
    },
    "data": [
        {
            "uuid": "f38f5c07-2af9-4ac7-8b5b-f1aac058e9f1",
            "name": "MinuteClinic",
            "address": "215 Park Ave S, New York, NY 10003, USA",
            "address_detail": {
                "street": "215 Park Ave S",
                  "address_line_1": "215 Park Ave S",
                "address_line_2": null,
                "city": "New York",
                "state": "NY",
                "zip": "10003"
            },
            "latitude": 40.7368055,
            "longitude": -73.9883164,
            "google_maps_link": "https://www.google.com/maps/place?q=place_id:ChIJRSZZ8KFZwokRjh4ZFfp2Ny8",
            "location_types": ["Retail Clinic"],
            "phone_numbers": [
                {
                    "phone": "6466028237"
                }
            ],
            "insurances": [
                {
                    "uuid": "998019bf-26fd-49a4-949a-3572eb58c0a1",
                    "carrier_association": "Aetna",
                    "carrier_brand": "Aetna",
                    "carrier_name": "Aetna",
                    "state": null,
                    "plan_name": "APCN Plus - Choice POS II",
                    "plan_type": null,
                    "metal_level": null,
                    "display_name": "Aetna - APCN Plus - Choice POS II",
                    "network": null,
                    "confidence": 4,
                    "category": "Group",
                    "codes": []
                },
              ... 28 more results...
            ],
            "npis": [
                "1487993564",
                "1730491945"
            ],
            "c_section_rate": 8.3,
            "distance": 0.32
        },
      ... 9 more results...
        
    ]
}

There is a lot that can be done here. Our mission to allow you to manipulate your location search as easily as possible!