Search for Locations Based on Organization Affiliation

Overview

Description: Filter and search for locations based on organizations with which they are affiliated.

Endpoint: /v1/custom/locations

Status: Live -- Please Contact Us to Learn More

Methods: GET

Example use-case: Narrow down a location search to only include locations that are affiliated with a health system that patients trust.

Methodology: Ribbon's location affiliation data relies on direct signal from a primary source (e.g., a health system's website) that a location is operated by a given organization .

📘

Organization Types

This endpoint currently contains information on Health Systems only.

We are also planning to release additional organization types (e.g., provider groups) in the future that will be included in this endpoint.

Please feel free to reach out to a Ribbon team member to learn more about our roadmap for this product!

Diving In

Searching for locations based on organizations aligns with the general functionality of the /locations/ endpoint as described in earlier pages of our documentation. The key difference is that if you have access to organization data within your custom /locations/ endpoint, you will be able to leverage the parameters below to filter providers accordingly.

Search Parameters

You can also use the following parameters for locations searches based on organizations of interest

Parameter	Description
organization_ids	Comma separated list of desired organization uuids. Filters to only locations who are affiliated with the given organization uuid(s).

Example Request - Locations

Below is an example request to search for all locations that are affiliated with Cleveland Clinic Health System within a 10 mile radius of Cleveland.

cURL

curl -X GET \
  'https://api.ribbonhealth.com//v1/custom/locations?organization_ids=86722ebb-1dd1-4846-a1a9-a7a9e36c944d&address=cleveland
&distance=10' \
  -H 'authorization: Bearer <your_token>'

Example Response - Locations

Below is the example response for this request, which shows roughly ~120 locations:

JSON

{
  "parameters": {
    "page": 1,
    "page_size": 25,
    "total_count": 118,
    "sort_by": "distance",
    "distance": 10,
    "geo": {
      "latitude": 41.49932,
      "longitude": -81.6943605
    },
    "address": "Cleveland, OH, USA",
    "organization_ids": [
      "86722ebb-1dd1-4846-a1a9-a7a9e36c944d"
    ]
  },
  "data": [
    {
      "uuid": "e830bc02-f452-4e86-a313-79b6b97e9b76",
      "name": "Cleveland Clinic Beachwood",
      "address": "315 Euclid Ave, Cleveland, OH 44114, US",
      "address_details": {
        "zip": "44114",
        "city": "Cleveland",
        "state": "OH",
        "street": "315 Euclid Ave",
        "address_line_1": "315 Euclid Ave",
        "address_line_2": null
      },
      "phone_numbers": [
        {
          "phone": "2164426700",
          "detail": "primary"
        }
      ],
      "confidence": 2,
      "location_types": [
        "Primary Care Clinic",
        "Independent Clinic"
      ],
      "insurances": [],
      "organizations": [
        {
          "uuid": "86722ebb-1dd1-4846-a1a9-a7a9e36c944d",
          "name": "Cleveland Clinic Health System",
          "organization_types": [
            "Health System"
          ],
          "websites": [
            {
              "url": "https://my.clevelandclinic.org/"
            }
          ],
          "ids": [],
          "address": "9500 Euclid Ave, Cleveland, OH 44195, US",
          "address_details": {
            "zip": "44195",
            "city": "Cleveland",
            "state": "OH",
            "street": "9500 Euclid Ave",
            "address_line_1": "9500 Euclid Ave",
            "address_line_2": null
          },
          "phone_numbers": [
            {
              "phone": "2164442200",
              "detail": "primary"
            }
          ]
        }
      ]
    },...117 more locations...
  ]
}