Edit or Add Fields to a Location

Overview

Description: This endpoint allows you to edit locations

Endpoints: /v1/custom/locations/{uuid}

Status: Live

Methods:PUT

Example use-case: You want to add "location_types" or unique custom fields (i.e. flags) to existing or newly created locations. You want to edit the "name" of an existing location.

Diving In

Adding Fields to a Location:
For this use-case, let's use an example. Let's say we want to power a location first search, which allows users to search only across specific location types. In order to enable this type of geospatial search, first we need to ensure such locations exist in our index.

For instance, let's say I want to add "Imaging Centers" to my /locations/ endpoint. Of course I could use the POST request outlined in the previous section to create new location objects, however if they already exist I may want to label them as "Imaging Centers".

As a refreshed, you can submit a GET request for the given location UUID to see the full object:

curl -X GET \
  https://api.ribbonhealth.com/v1/custom/locations/600fab02-dc15-426b-80ef-fa88c9852072 \
  -H 'Authorization: Token <Your Token>' \
  -H 'Content-Type: application/json' \

You can see in the response below, that the given location, "New York Doctors", does not include a field "location_types".

{
    "uuid": "600fab02-dc15-426b-80ef-fa88c9852072",
    "name": "New York Doctors",
    "address": "65 W 13th St, New York, NY 10011, US",
    "address_details": {
        "street": "65 W 13th St",
        "address_line_1": "65 W 13th St",
        "address_line_2": null,
        "city": "New York",
        "state": "NY",
        "zip": "10011"
    },
    "latitude": 40.7365926,
    "longitude": -73.9967419,
    "google_maps_link": "https://www.google.com/maps/@40.7365926,-73.9967419?q=65%20W%2013th%20St%2C%20New%20York%2C%20NY%2010011%2C%20US",
    "phone_numbers": [
        { "phone": "2124142800" }
    ]
}

Use the UUID of the existing location object and submit the following PUT request to add "location_types" to the location with the value you wish to add:

curl -X PUT \
  'http://api.ribbonhealth.com/v1/custom/locations/600fab02-dc15-426b-80ef-fa88c9852072' \
  -H 'Authorization: Token <Your Token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_types": ["Imaging Center"]
}'

Voila! The given location now includes the field "location_types" and it is set to ["Imaging Center"].

Now, let's say it turns out I have too many imaging centers and my users are overwhelmed. To help them out, I want to add priority flags to the establishments I highly recommend. In addition, it turns out this location is also an Urgent Care center, so I want to add that classification into the "location_types" field.

To add a custom field, "priority_flag", to a location and also edit/add to "location_types":

curl -X PUT \
  'http://api.ribbonhealth.com/v1/custom/locations/600fab02-dc15-426b-80ef-fa88c9852072' \
  -H 'Authorization: Token <Your Token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_types": ["Imaging Center", "Urgent Care"],
    "priority_flag": true
}'

Once you have added the necessary "location_types" and flags to your locations, your users can search for nearby locations by passing in these parameters (see "Search for Nearby Locations / Facilities" section).

Note: You cannot edit or remove certain core fields of location objects. Location objects are tied to their lat/long and google_maps_link, therefore these fields are immutable.

❗️

Editing a location object can also affect providers who have the given location listed on their profile

When you leverage the /locations/ endpoint to edit a location object, these updates are not limited to the given object within the /locations/ endpoint, but also flow through to the /providers/ endpoint. For instance, in the example above, if 50 providers practice at "New York Doctors" at "65 W 13th St, New York, NY 10011, US", then updating the 'location_types' or adding a custom field will also appear on each of those 50 providers' profiles when you view them at the /providers/ endpoint.

Note #1: Updating "phone_numbers" or "confidence" at the /locations/ endpoint will not flow through to providers' profiles, as both phone number and confidence score is unique to the provider at the given location.

Note #2: Updates made to provider<>locations at the /providers/ endpoint (docs) will override updates made to the 'global' location via the /locations/ endpoint, but only for the given provider.

🚧

New feature in API Version [2021-05-13]

We have released a new feature that introduces data type validation to stock Ribbon Fields in API Version [2021-05-13]. This validation applies when you edit certain fields of a location.

For more information, please refer to this changelog.

🚧

Be careful of editing a location's address

If you wish you change the 'address' of a location, you would be better suited to create a new location altogether with the desired address. As mentioned above, the lat/long and link are immutable, therefore if you update a location's address from 100 Main Street to 1000 Main Street which is a mile away, the lat/long will not update. Instead, you should create a new location object (docs) at the desired address (e.g. 1000 Main Street).

📘

Editing a location's insurances works differently than the process outlined above!

Editing a location's insurances works slightly differently. We maintain a different standard for key fields like insurances so that data can be consistently merged and resolved for these fields as our dataset updates.

See here for more details on how to edit a location's insurances.