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: Bearer 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:
| 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) |
national_bluecard | True | Optional | Defaults to true unless otherwise specified. Boolean input that enables an API search to automatically default to the National BlueCard EPO/PPO Network whenever a member searches for out-of-state, in-network care and is covered by a BCBS Association PPO insurance plan. Use the parameter in conjunction with the address parameter and either the insurance_ids or insurance fuzzy search parameters. |
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.
Updated 26 days ago