What do the updates include?

High Level Summary

OS Hub is in the process of developing the v1/production-locations endpoint, which will support GET and POST calls for downloading data and uploading production locations to OS Hub as well as provide expanded search functionality. Eventually, this endpoint is meant to replace the /facilities endpoint, which currently supports API upload and download use cases as well as OS Hub’s front-end search experience. Initially, the v1/production-locations endpoint and expanded search functionality will be available to API users only, with integration on OS Hub's front-end to follow.

Note: Aside from providing your input, there is no action that you need to take at this time. We will share finalized plans for transitioning to the new endpoint and steps you need to take in a subsequent update. For now, we ask for your input as we plan to rollout the v1/production-locations endpoint.

Why is OS Hub making these updates?

The introduction of the v1/production-locations endpoint is meant to provide additional functionality not available with the /facilities endpoint. Specifically:

• For GET requests, we are improving search capabilities to include support for fuzzy search and provide additional search options, like searching for a keyword that appears anywhere within a profile OR in a specific field.
• For POST requests, this new endpoint will also support API moderation and enable our team to more easily identify and remediate low quality data uploaded to OS Hub.

What are the key differences between /facilities and v1/production-locations?

• v1/production-locations WILL:

  • Introduce API versioning

  • Support fuzzy search and provide additional search options (e.g. keyword, local language name, address search)

  • Support proximity search, in addition to text-based search, for addresses

  • Forward data uploaded via API to a consolidated moderation queue maintained by the OS Hub team

• v1/production-locations WILL NOT:

  • Support the “create” parameter in POST requests

  • Respond with URLs for confirm/reject in the case of a potential match

A few key points...

How will GET v1/production-locations replace the create parameter?

Some API users make use of the create=false parameter when sending a POST request to /facilities. This is a way to search for profiles with a similar name and address to a location they want to upload without actually publishing the data on OS Hub.

• Because GET requests to the /facilities endpoint do not support fuzzy search, the way to find non-exact matches on OS Hub is to access the deduplication algorithm via a POST request to /facilities.

• Given that v1/production-locations will have the ability to return fuzzy search results and do proximity searches around an address, the use case of looking for records with similar names and addresses (but not posting them) will be supported with a GET request, similar to how other REST APIs support search functionality.

Why will the v1/production-locations NOT return confirm/reject URLs in the case of a potential match?

When a POST request is submitted to /facilities and it results in a potential match, the system currently returns two URLs - one corresponding to "confirm," the other to "reject." The idea is that the API user will respond with the appropriate URL to either confirm that an existing facility is in fact a match OR reject that an existing facility is a match.

• In practice, we find that the majority of POST requests that result in a potential match do not get confirmed or rejected - meaning that the data remains in a pending state and is not published on OS Hub.

• We are re-building some of our moderation tools in order to support our data team in more easily identifying records that need moderation and being able to complete that moderation efficiently.

• Instead of API users having the responsibility to make a confirm or reject decision, the OS Hub data team will take on this responsibility to ensure that records do not linger in pending status for an extended period of time.

What else do you need to know?

We want your feedback before we finalize our rollout plans for v1/production-locations, especially:

• Both endpoints (/facilities and v1/production-locations) will be functional for an overlapping period of time. What are your expectations around this timing?
• How will the introduction of v1/production-locations impact your work? What is the level of effort for any necessary code changes on your side?
• Any questions or concerns about changes for the create parameter or data moderation?

We'll be reaching out to API users directly, but please also feel free to reach out to us at support@opensupplyhub.org to share your feedback.