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": 50,
        "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:

ParameterExample ValueRequired/OptionalDetail
addressBoston, MAOptional (required if no longitude and latitude coordinates)Our API geocodes this into longitude/latitude coordinates to use for distance calculations
nameMinuteClinicOptionalLeverage the "name" search parameter for a 'fuzzy' search on location name.
distance50OptionalConstrains 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_typesUrgent Care
Hospital
Dialysis Center
etc.
OptionalThis 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.
location37.7489816,-122.4802092OptionalComma separated list latitude, longitude coordinates
location_idsuuid1,uuid2,uuid3OptionalComma separated list of desired practice location uuids.
insurance_idsuuid1,uuid2,uuid3OptionalComma separated list of desired insurance uuids. See all facilities who accept a given insurance(s).
insurance_carrier_nameAetnaOptionalString 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_confidence3OptionalInteger 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.


What’s Next