Search for Providers

Overview

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

Endpoint: /v1/providers

Status: Live

Methods: GET

Example use-case: Build a listing of doctors for a user searching for doctors based on important parameters like specialty, location, medical insurance, patient satisfaction, etc.

Diving In

The providers API allows you to pull information on nearby doctors (and/or other medical providers) anywhere in the United States, ranging from basics like location and contact information to granular detailed information on the doctor like accepted insurance and patient satisfaction ratings.

To start with an example, the '/v1/providers' endpoint responds with a list of providers sorted by proximity from the given address. Let's say we want to find a Cardiologist in New York City who accepts the BCBS BlueCard PPO insurance plan.

To see it in action, we are going to enter in three parameters in this query:

• address=New York, NY.
• insurance_ids=b8581687-2b4e-4f2f-91a9-9128f5bec540
• specialty_ids=1de33770-eb1c-47fa-ab3e-f9a4ab924d9d
  Note: Instead of specialty_ids you could also also use the specialty parameter:
• specialty=cardiology

With these parameters, we're searching for Cardiologists in the New York area who accept Blue Cross Blue Shield - BlueCard - PPO!

Search Parameters

You can search for providers based on any of the core fields associated with a provider, for example:

Parameter	Description
address	String input of an address that will be interpreted and geocoded in real time.
specialty_ids	Comma separated list of desired specialty uuids. See all providers who specialize in the given specialties.
specialty	String input of a provider specialty that will be interpreted and matched to the closest specialty, dealing with basic typos and colloquial names for providers. For example, to find Gastroenterologists you could search any of the following: - gastroenterology - gastroenterologist - gastro - stomach doc - gastrooentrology
insurance_ids	Comma separated list of desired insurance uuids. See all providers who accept a given insurance(s).
name	String input of a full, first, last, or partial name.
location_ids	Comma separated list of desired practice location uuids. See all providers who see patients at any of the given practice locations.
location	Latitude/longitude pair of coordinates in lieu of a string address (i.e. location=37.7489816,-122.4802092).
npis	Comma separated list of desired NPIs (i.e. use this to search for 5 specific doctors).
provider_types	Comma separated list of the 'types' of providers you are searching for. Provider types are higher level groupings of specialties. Here are a few key provider types: - Doctor - Nursing - Dental Providers - Optometry - Chiropractic Providers See the Specialties Reference Endpoint for a list of all specialties and their provider types.
min_location_confidence	Integer input (0-5) of the minimum confidence threshold for returned provider locations. min_location_confidence=3 will only display providers' locations that have a confidence 3 or higher. If a provider has a 5 locations, one of which is greater than 3, only the high confidence location will be included in the returned JSON output. Note: when this parameter is in use, the maximum number of records accessible is 1000 (i.e. if you maintain the default page_size of 25, the last page that can be paginated to is 40)
min_confidence	Integer input (0-5) of the minimum confidence location you wish the returned providers to have (i.e. min_confidence=4 will only display providers who have a location with confidence 4 or higher). This is a more performant but 'simpler' version of min_location_confidence parameter.
gender	String input of either m or f to filter to only medical providers of the inputted gender.
max_age	Integer input (i.e. 50) to filter to only medical providers under the inputted age.
min_age	Integer input (i.e. 50) to filter to only medical providers above the inputted age.
language	Fuzzy search based on a string input to filter to only medical providers providers who speak / whose office staff speak the inputted language.

🚧

Searching Specialty by String

Instead of using the specialty_ids parameter, you could use the specialty parameter which interprets a string value for each specialty. For example, instead of using the specialty uuid for Cardiologist, the following calls would work as well:

• https://api.ribbonhealth.com/v1/providers?specialty=cardiology
• https://api.ribbonhealth.com/v1/providers?specialty=cadiologist
• https://api.ribbonhealth.com/v1/providers?specialty=heart doctor

Example Request

cURL

curl -X GET \
  'https://api.ribbonhealth.com/v1/providers?address=33 Irving Pl, NYC&specialty_ids=1de33770-eb1c-47fa-ab3e-f9a4ab924d9d&insurance_ids=b8581687-2b4e-4f2f-91a9-9128f5bec540' \
  -H 'authorization: Token <your_token>'

The JSON object response to the above query is below. This response includes a list of 20 doctors under results. The response includes typical pagination links under next and previous.

We can also see what parameters are driving the query under parameters, which can be useful in making sure that the search parameters you're passing are properly received. You'll notice a few new components in the parameters that were not originally passed into the query.
1) geo includes longitude & latitude coordinates interpreted from the given address. This helps us understand the central location that distance is being calculated for each doctor. In this case, we see that the string New York, NY resulted in Latitude, Longitude coordinates of 40.7351327, -73.9903544.

2) distance shows the proximity radius of doctors displayed. We can see here that the API is using a default, which is a distance radius of 10 miles. If this radius is too narrow or too broad, it can be configured with the distance parameter.

📘

total_count shows the number of results returned for the given search

JSON

{
   "parameters": {
        "total_count": 141,
        "page": 1,
        "page_size": 25,
        "sort_by": "distance",
        "distance": 10,
        "geo": {
            "latitude": 40.7351327,
            "longitude": -73.9881657
        },
        "address": "33 Irving Pl, New York, NY 10003, USA",
        "specialty_ids": [
            "1de33770-eb1c-47fa-ab3e-f9a4ab924d9d"
        ],
        "insurance_ids": [
            "b8581687-2b4e-4f2f-91a9-9128f5bec540"
        ]
    },
  "data": [
    {
      "first_name": "Alexander",
      "middle_name": "J",
      "last_name": "Greenstein",
      "age": 42,
      "gender": "m",
      "ratings_count": 38,
      "ratings_avg": 8.74,
      "degrees": [...],
      "specialties": [...],
      "languages": [...],
      "educations": [...],
      "insurances": [...],
      "provider_types": [...],
      "locations":[...],
      "online_profiles": [...],
      "distance": 0.04,
      "npi": "1992964035"
    },
...24 more Doctors...      
  ]
}