Include or Exclude Specific Fields in a Provider Search

Overview

Description: The Providers Search endpoint supports the fields and _excl_fields query parameters to limit what fields are included on Provider objects returned in the search response. By doing so, the size of Provider objects decreases and response latency is reduced.

The fields parameter is an inclusive filter that accepts a comma-separated string of field names to include on Provider objects, while the _excl_fields parameter is an exclusive filter that accepts a comma-separated string of field names to exclude from Provider objects.

Endpoint: /v1/custom/providers

Status: Live

Methods: GET

Example use-case: You want to create a page for provider search results and only want to display certain fields of information, such as name, phone number, or specialty.

Diving In

Let's do a regular search for Dermatologists (specialty UUID b9dc44e1-6add-41f8-8df4-a8ef9cea706a) close to the zip code 10014:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=b9dc44e1-6add-41f8-8df4-a8ef9cea706a&address=10014' \
  -H 'Authorization: Token <Your Token>' \

We get 1,553 results for this search in the NYC area.

Looking into the first provider result, we can see that there is a lot of valuable detailed data that Ribbon provides in the response. We've truncated everything after Specialties data in this example, but there are over nearly 200 rows of data for this single provider alone.

We've seen certain providers with over 9,000 rows of data if they practice at a lot of locations. Holy cannoli!

{
    "parameters": {
        "page": 1,
        "page_size": 25,
        "total_count": 1553,
        "sort_by": "distance",
        "address": "New York, NY 10014, USA",
        "distance": 10.0,
        "geo": {
            "latitude": 40.7366138,
            "longitude": -74.0094471
        },
        "specialty_ids": [
            "b9dc44e1-6add-41f8-8df4-a8ef9cea706a"
        ]
    },
    "data": [
        {
            "npi": "1144329830",
            "first_name": "Yelena",
            "middle_name": null,
            "last_name": "Yeretsky",
            "status": "active",
            "age": null,
            "gender": "f",
            "ratings_count": 6,
            "ratings_avg": 8.34,
            "degrees": [
                "DO"
            ],
            "educations": [
                {
                    "type": "Medical School",
                    "year": 1999,
                    "education": {
                        "name": "NYIT College Of Osteopathic Medicine",
                        "uuid": "da1511d1-4d28-432f-8921-a8f0dfa8b6df"
                    }
                }
            ],
            "is_pcp": false,
            "specialties": [
                {
                    "uuid": "b9dc44e1-6add-41f8-8df4-a8ef9cea706a",
                    "taxonomy_code": "207N00000X",
                    "board_specialty": "Dermatology",
                    "board_sub_specialty": "None",
                    "non_md_specialty": null,
                    "non_md_sub_specialty": null,
                    "provider_name": "Dermatologist",
                    "colloquial": "Skin Care Doctor",
                    "display": "Dermatology",
                    "taxonomy_1": "Allopathic & Osteopathic Physicians",
                    "taxonomy_2": "Dermatology",
                    "taxonomy_3": null,
                    "provider_type": "Doctor",
                    "is_primary": true
               }
            ],
          ...
          ...
}

For the majority of situations, you don't need all of this information, so let's see a couple of ways you can reduce the response size to make your searches blazingly fast!

📘

A B C, easy as 1 2 3!

You can include or exclude nested rows of data as well by using standard JSON syntax. For example, fields = education.name will only pull in the names of the institutions providers studied at in the response.

Let's say you only care about the locations that a provider practices at. A search that calls for this specific field in the response looks like:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=b9dc44e1-6add-41f8-8df4-a8ef9cea706a&address=10014&fields=locations' \
  -H 'Authorization: Token <Your Token>' \

You can see that the response is greatly reduced in size:

{
    "parameters": {
        "page": 1,
        "page_size": 25,
        "total_count": 1553,
        "sort_by": "distance",
        "address": "New York, NY 10014, USA",
        "distance": 10.0,
        "geo": {
            "latitude": 40.7366138,
            "longitude": -74.0094471
        },
        "specialty_ids": [
            "b9dc44e1-6add-41f8-8df4-a8ef9cea706a"
        ],
        "fields": [
            "locations"
        ]
    },
    "data": [
        {
            "npi": "1144329830",
            "locations": [
                {
                    "name": null,
                    "uuid": "1829ce37-495b-4c3e-a7fe-09c61377ec09",
                    "faxes": [],
                    "address": "223 W 10th St, New York, NY 10014, US",
                    "latitude": 40.7340279,
                    "longitude": -74.0051727,
                    "confidence": 2.0,
                    "insurances": [],
                    "phone_numbers": [
                        {
                            "phone": "2122558023",
                            "details": "primary"
                        },
                        {
                            "phone": "9737596569",
                            "details": "secondary"
                        }
                    ],
                    "location_types": [],
                    "address_details": {
                        "zip": "10014",
                        "city": "New York",
                        "state": "NY",
                        "street": "223 W 10th St",
                        "address_line_1": "223 W 10th St",
                        "address_line_2": null
                    },
                    "google_maps_link": "https://www.google.com/maps/@40.7340288,-74.0051757?q=223%20W%2010th%20St%2C%20New%20York%2C%20NY%2010014%2C%20US",
                    "accepting_new_patients": null,
                    "distance": 0.29
                },
              ...
              ...
            ]
}

Similary, we can also exclude locations from the response with a search that looks like:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/providers?specialty_ids=b9dc44e1-6add-41f8-8df4-a8ef9cea706a&address=10014&_excl_fields=locations' \
  -H 'Authorization: Token <Your Token>' \

If you try this out, you'll see that locations are nowhere to be found in the response!

Both of these methods reduce the response time of requests and allow you to build more delightful user experiences using Ribbon's API!