Search for Locations

Endpoint for finding locations / facilities

Overview

Description: The locations endpoint allows you to search for a variety of different service locations, including specific location types (i.e. urgent care centers)

Endpoint: /v1/custom/locations

Status: Live

Example use-case: Display a map of all nearby urgent care facilities so a patient can get care immediately.

Diving In

This endpoint allows the user to retrieve a list of service locations and/or facilities based on geospatial search or text search.

Example Request

Below is an example of a call to see all urgent care or retail clinics (i.e. Minute Clinic) within 50 miles of Union Square, New York:

curl -X GET \
  'https://api.ribbonhealth.com/v1/custom/locations?address=union square nyc&distance=50&location_types=Urgent Care,Retail Clinic' \
  -H 'authorization: Token your_token'

Example JSON Output

The response normalizes and geocodes the inputted address and also displays the search 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",
        "location_types": [
            "Urgent Care",
            "Retail Clinic"
        ]
    },
    "data": [
        {
            "uuid": "48d4eb27-d82b-4ea4-8ad0-4bcb2c46a960",
            "name": "Citymd Urgent Care",
            "address": "14 W 14th St, New York, NY 10011, US",
            "address_details": {
                "zip": "10011",
                "city": "New York",
                "state": "NY",
                "street": "14 W 14th St",
                "address_line_1": "14 W 14th St",
                "address_line_2": null
            },
            "latitude": 40.7361613,
            "longitude": -73.9946005,
            "google_maps_link": "https://www.google.com/maps/search/?api=1&query=40.7361613%2C-73.9946005&query_place_id=ChIJRyzXr5T8ZUARZdexX8-bA4s",
            "phone_numbers": [
                {
                    "phone": "2123900558",
                    "detail": "primary"
                },
                {
                    "phone": "2126580676",
                    "detail": "secondary"
                }
            ],
            "confidence": 3,
            "location_types": [
                "Urgent Care"
            ],
            "insurances": [
                {
                    "uuid": "24617022-92b3-4b9f-af1c-4df21ad6fb6f",
                    "carrier_association": "MultiPlan",
                    "carrier_brand": "MultiPlan",
                    "carrier_name": "MultiPlan",
                    "state": null,
                    "plan_name": "Preventive Services Only",
                    "plan_type": "PPO",
                    "metal_level": null,
                    "display_name": "MultiPlan - Preventive Services Only - PPO",
                    "network": null,
                    "confidence": 4,
                    "category": "Group",
                    "codes": []
                },
              ...11 more results...
            ],
            "npis": [
                "1649899832",
                "1730491945"
            ],
            "distance": 0.19,
        },
      ... 9 more results...
        
    ]
}

Parameters

The parameters this endpoint can receive are listed below. Note that the user has two options for entering in a location, both entering in an address, such as a street or city. Without longitude and latitude coordinate, the API will convert this for the user:

Parameter

Example Value

Required/Optional

Detail

address

Boston, MA

Optional (required if no longitude and latitude coordinates)

Our API geocodes this into longitude/latitude coordinates to use for distance calculations

name

MinuteClinic

Optional

Leverage the "name" search parameter for a 'fuzzy' search on location name.

distance

50

Optional

Constrains the search to facilities within Y miles of the center point (in this case, without specifying the radius, the API defaults to 10 miles)

location_types

Urgent Care
Hospital
Dialysis Center
etc.

Optional

This is a comma separated list of values that filter to what kind of facilities to show. We categorize locations into 34 types. Clients can add their own locations with unique location_types, and they will also be included in the search.

location

37.7489816,-122.4802092

Optional

Comma separated list latitude, longitude coordinates

location_ids

uuid1,uuid2,uuid3

Optional

Comma separated list of desired practice location uuids.

insurance_ids

uuid1,uuid2,uuid3

Optional

Comma separated list of desired insurance uuids. See all facilities who accept a given insurance(s).

insurance_carrier_name

Aetna

Optional

String input of carrier_name in order to search for all providers that take at least one plan from a given insurance carrier.

Find the individual valid carrier_name values from the insurance objects returned in the Insurances Reference Endpoint.

Note: This input must be an exact string match to work

min_confidence

3

Optional

Integer input (0-5) of the minimum confidence location you wish the returned (i.e. min_confidence=4 will only display locations who have a location with confidence 4 or higher)

🚧

If you add a custom field to one or more locations, you will be able to filter on it using a parameter!

Later in this section, we will discuss editing and adding fields to locations. In those cases, you can filter on your own custom fields by adding parameters to your GET request URLs.