GuidesTry Ribbon!

Best Practices for Find Care Use Case

Suggest Edits

Powering Search Bar Drop Down

We recommend leveraging our reference endpoints to display drop down menus for available insurances, specialties and provider types. Some of our customers cache this data weekly to improve the search performance.

For insurances, we recommend using the carrier_name and display_name to populate the drop down menu.

Searching for a Provider

To yield the highest quality results, we recommend combining the below filters for each provider search request.

  • Geographic Filter: While our parameters are quite flexible, we recommend a distance of 10 miles or less. Note, 10 miles is the distance by default.
  • Insurance Filter: We recommend restricting results to only display providers with locations that are in-network by using the location_insurance_ids parameter.
  • Confidence Filter: Given the frequency of data refreshes, it is best practice to use min_location_confidence=3 to only display locations with a probability of greater than 70%. Please, note the volume of high quality results can vary based on a variety of factors such as provider specialty, geographic area and insurance network.
  • Specialty Filter: We recommend restricting results by a provider's specialty using either a fuzzy search with specialty or by specialty UUIDs using specialty_ids.
curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?address=10003&location_insurance_ids=6ab9d1d3-b969-4352-9fac-68b6494cbe7b&distance=10&min_location_confidence=3&specialty=Derma' \
  -H 'authorization: Bearer <your_token>'

"parameters": {
        "page": 1,
        "page_size": 25,
        "total_count": 586,
        "sort_by": "distance",
        "address": "New York, NY 10003, USA",
        "distance": 10.0,
        "geo": {
            "latitude": 40.7322535,
            "longitude": -73.9874105
        },
        "location_insurance_ids": [
            "6ab9d1d3-b969-4352-9fac-68b6494cbe7b"
        ],
        "min_location_confidence": 3.0,
        "specialty": {
            "uuid": "b9dc44e1-6add-41f8-8df4-a8ef9cea706a",
            "display": "Dermatology",
            "taxonomy_1": "Allopathic & Osteopathic Physicians",
            "taxonomy_2": "Dermatology",
            "taxonomy_3": null,
            "provider_type": "Doctor"
        }

📘

What are provider confidence scores?

A confidence score is a number from 1 to 5 that represents the probability that a provider practices at a location and is determined by our machine learning model. Our machine learning model scores all provider locations using a truth set and thousands of data sources.

Confidence score of 5 indicates that the data point has been manually verified within the past 90 days.
Confidence score of 4 represents a probability greater than 80%
Confidence score of 3 represents a probability between 60 and 80%
Confidence score of 2 represents a probability between 40 and 60%
Confidence score of 1 represents a probability less than 40%

Improving API Performance

Reduce the response size by using the fields parameter to only return fields that are used to power the UI and max_insurances to limit the number of insurances returned for each provider. Note max_insurances can only be used on the /v1/custom/providers/{npi} endpoint.

For example, if you want to show a detailed view on a provider's demographic info you could restrict results to a specific npi using the npis param and particular fields using the fields param as shown below.

curl --location --request GET 'https://api.ribbonhealth.com/v1/custom/providers?fields=first_name,last_name,educations, gender, age&npis=1659480515' \
--header 'authorization: Bearer <your token>'

{
    "parameters": {
        "total_count": 1,
        "geo": {
            "latitude": 40.75368539999999,
            "longitude": -73.9991637
        },
        "address": "New York, NY 10001, USA",
        "fields": [
            "educations",
            "age",
            "last_name",
            "first_name",
            "gender"
        ]
    },
    "data": [
        {
            "npi": "1659480515",
            "first_name": "Helen",
            "last_name": "Yoo Bowne",
            "age": 60,
            "gender": "f",
            "educations": [
                {
                    "type": "Fellowship",
                    "year": null,
                    "education": {
                        "name": "Beth Israel Deaconess Medical Center",
                        "uuid": "840cd4c1-f8d1-499c-8ba8-43825c863a2e"
                    }
                },
                {
                    "type": "Internship",
                    "year": null,
                    "education": {
                        "name": "Beth Israel Deaconess Medical Center",
                        "uuid": "840cd4c1-f8d1-499c-8ba8-43825c863a2e"
                    }
                },
                {
                    "type": "Residency",
                    "year": null,
                    "education": {
                        "name": "New York Medical College",
                        "uuid": "7b7f7721-7d08-47fe-b88a-aa1c5ba7a12e"
                    }
                },
                {
                    "type": "Medical School",
                    "year": 1994,
                    "education": {
                        "name": "Albert Einstein College of Medicine - Jack and Pearl Resnick Campus",
                        "uuid": "ffc28911-9c0a-4886-93a1-72f3ef938afc"
                    }
                }
            ]
        }
    ]
}

Updated 26 days ago