Normalize Addresses Using the Locations Endpoint

Overview

Description: This endpoint allows you to normalize addresses to a common standard (i.e. USPS).

Endpoints: /v1/custom/locations

Status: Live

Methods:POST

Example use-case: You have an existing provider directory that contains provider addresses that have been aggregated from a variety of sources (i.e. multiple contracted provider groups / hospitals) and as such does not follow a single standard. This causes issues with duplicative or incorrect information. Use this endpoint to clean up your existing address data and maintain a high standard moving forward.

Diving In

Use a POST request to the /v1/custom/locations endpoint in order to normalize the inputted address. For example:

cURL

curl -X POST \
  'https://api.ribbonhealth.com/v1/custom/locations' \
  -H 'Authorization: Bearer <Your Token>' \
  -H 'Content-Type: application/json' \
  -d '{
	"address":"33 Irving Place, New York, NY"
	}'

We get the following result:

JSON

{
    "error": {
      	"code": "conflict",
        "message": "resource already exists"
    },
    "data": {
        "uuid": "777b9fda-a9db-4990-bb71-f29e24d3be75",
        "name": null,
        "address": "33 Irving Pl, New York, NY 10003, US",
        "address_details": {
            "street": "33 Irving Pl",
            "address_line_1": "33 Irving Pl",
            "address_line_2": null,
            "city": "New York",
            "state": "NY",
            "zip": "10003"
        },
        "latitude": 40.7351327,
        "longitude": -73.9881657,
        "google_maps_link": "https://www.google.com/maps/@40.7351327,-73.9881657?q=33%20Irving%20Pl%2C%20New%20York%2C%20NY%2010003%2C%20US"
    }
}

The result above shows a normalized address structure for the inputted string. This is displayed both as a combined/full address ("address") as well as broken down into address components ("address_details"). We also provide a lat/long for the given address and a google maps link for plotting purposes.

❗️

"Resource Already Exists" error can be ignored!

Note: the "error" can be ignored in this case. While this POST request is traditionally used to 'create new locations' in the Ribbon API, it is also used to normalize addresses. For this use case, the error is irrelevant - either a location will be found within Ribbon's API and this error will appear or no location will be found and no error will appear. Either way, the inputted address will be geocoded and normalized within the "data" field.