This quick-start guide includes an overview of the Open Supply Hub API and examples of the most common use cases.
Click here to see a demonstration of the API.
Click here to follow along with a step-by-step tutorial for connecting to the API.
Quick Start Guide
Applications include:
- Searching for facilities by id, name, country, sector, product type, facility type, processing type, parent company and number of workers.
- Finding matches to facilities in your database with OS Hub's matching algorithm.
- Disclosing your supply chain data anonymously (only available with certain packages).
The list of supported endpoints and parameters can be found below. The endpoints are grouped by the base URL path and then by GET or POST functionality. Each endpoint description includes a listing of parameters that can be used to build requests.
Getting Connected
To make requests to the OS Hub API, you can sign up for a trial or purchase a subscription package. To find out more about a trial or to purchase a package visit Connect to OS Hub's API.
You can check if you have access to the API by going to My Account > Settings > API on the OS Hub map site. If you don't see a tab called "API" in the settings menu, that means you do not have access.
Environments
There are two environments that API users can access. One is a staging environment where you can make test calls and the other is OS Hub's production environment. Data moderation is regularly performed on production, and in the event that you send test traffic to the production environment, it may be removed.
The base URL for the OS Hub staging environment is: https://staging.opensupplyhub.org/api/
The base URL for the OS Hub Production environment is: https://opensupplyhub.org/api/
Authorization Header
An API Token is needed to make requests to OS Hub API endpoints. You can generate a token at My Account > Settings > API > Generate New API Token.
Example authorization header.
Note that the word “Token” with a space after it needs to precede the token value. E.g. “Token {token value}”
Endpoint Listing
Endpoint: /facilities/
The 'facilities' endpoint can be used to download (get) facilities based on a set of search criteria OR to upload (post) facilities to OS Hub.
Use Case: GET Facility by OS ID
Base URL: https://opensupplyhub.org/api/facilities/
Returns a facility with all data that has been contributed about that facility; details parameter defaults to true when searching by a single ID.
Example of searching by an OS ID. Response includes all data that has been contributed about a facility and info about the contributors.
Use Case: GET Facilities based on search criteria
Base URL: https://opensupplyhub.org/api/facilities/
Returns a list of facilities in GeoJSON format for a given query. Maximum of 50 facilities per page if the detail parameter is false or not specified, 10 if the detail parameter is true.
PARAMS
detail - (Boolean) Set this to true to return additional details about contributors and extended fields with each result. Setting this to true will make the response significantly longer and may make the response slower to return.
number_of_public_contributors - (Boolean) Set this to true to return the number of public contributors that have uploaded data for each facility in the results.
combine_contributors - (String) The search will default to search the union of two or more contributors; if you want to search the intersect, set combine_contributors = AND.
sort_by - (String) The search results will be sorted by most to least contributors by default; if you prefer to sort alphabetically, set sort_by = NAME.
page - (Integer) A page number within the paginated result set.
pageSize - (Integer) Number of results returned per page; maximum of 50 per page when detail parameter = false or is not specified, maximum of 10 per page when detail parameter is true.
Example with no path variables set. The API response is returning 50 entries per request by default; page and pageSize can be used to manage large amounts of data.
PATH VARIABLES
q - (String) A search term that searches on name and OS ID.
countries - (String) A two character country code; use GET /countries/ to pull a list of country names and associated country code.
contributors - (Integer) A contributor ID; use GET /contributors/ to pull a list of contributor names and associated IDs.
product_type - (String) This filters by type of product associated with a facility; use GET /product-types/ to pull a list of product types that have been uploaded to OS Hub.
sector - (String) This filters by the sector a facility is associated with; use GET /sectors/ to pull a list of sectors available on OS Hub.
contributor_types - (String) This is the type of contributor you wish to filter to; use GET /contributor-types/ to pull a list of available contributor types.
parent_company - (String) This can be a contributor ID or name of a parent company; use GET /parent-companies/ to pull a list of parent companies names.
facility_type - (String) This filters by type of facility; use GET /facility-processing-types/ to pull a list of supported facility types and the processing types associated with them.
processing_type - (String) This filters by the type of processing activity that occurs at the facility; use GET /facility-processing-types/ to pull a list of supported facility types and the processing types associated with them.
Use Case: POST Facility to OS Hub
Base URL: https://opensupplyhub.org/api/...
Upload facility data and look for existing matches in the OS Hub database. By default, a new facility is created when there is no match or, in the case of a confident match, the facility details uploaded by the contributor will be added to the existing facility record.
PARAMS
create - (Boolean) If set to false, a new facility will NOT be created when there is no match to an existing facility.
public - (Boolean) If set to false, the contribution will be attributed to the contributor type instead of the contributor name. This parameter is only available with certain API packages.
REQUEST PAYLOAD
The request must be submitted in JSON format and, at minimum, include “name”, “country”, and “address” fields.
Required:
name - (String) The name of the facility
address - (String) Street address of the facility, including all address elements except for country.
country - (String) Country where the facility is located.
Example payload with "product type", "sector" and "parent company", in addition to the minimum required fields.
Optional:
product_type - (String) Indicates a product type produced/processed by the facility. Product types can be uploaded in this field or in the field sector_product_type.
sector - (String) Indicates the sector that a given facility is associated with. Sector can be uploaded in this field or in the field sector_product_type.
sector_product_type - (String) This field can include product types and/or sectors associated with the facility. If a value uploaded as part of this field matches a sector value on OS Hub’s supported sector list, it will be displayed as a sector on the facility profile. All other values uploaded in this field will be displayed as product types.
facility_type - (String) Indicates the facility type (e.g. “Final Product Assembly”). See OS Hub’s taxonomy for supported facility types.
processing_type - (String) Indicates the type of processing activity that takes place at a facility (e.g. “printing”). If any processing type matches one of the types on OS Hub’s taxonomy, the associated facility type will also be added to the facility profile as a facility type, even if it is not directly uploaded.
facility_type_processing_type - (String) This field can include facility type and processing type. If any processing type matches one of the types on OS Hub’s taxonomy, the associated facility type will also be added to the facility profile as a facility type, even if it is not directly uploaded.
parent_company - (String) Indicates the company that holds majority ownership of the facility.
number_of_workers - (Integer or String) A number, or range, of workers employed at the facility. E.g.: “100” or “100-150” are accepted values.
Endpoint: /moderation-events/merge/
Use Case: GET /moderation-events/merge/
Base URL: https://opensupplyhub.org/api/...
Returns a list of facilities uploaded by the contributor that have been merged by the OS Hub Data Team along with the current ID, original ID, date that original ID was created and date that the merge occurred.
PARAMS
- detail - (Boolean) Set this to true to return additional details about merge events, namely address and name of the original facility.
- date_greater_than_or_equal - (String) Specify the date in the YYYY-MM-DD format to retrieve merge events that occurred on or after the specified date.
- date_less_than - (String) Specify the date in the YYYY-MM-DD format to retrieve merge events that occurred before the specified date
Sample Response (with "details" = "true"):
Endpoint: /countries/
Use Case: GET /countries/
Base URL: https://opensupplyhub.org/api/countries/
Returns a list of country choices as tuples of country codes and names. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /contributors/
Use Case: GET /contributors/
Base URL: https://opensupplyhub.org/api/contributors/
Returns list contributors as a list of tuples of contributor IDs and names. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /product-types/
Use Case: GET /product-types/
Base URL: https://opensupplyhub.org/api/product-types/
Returns a list of product types that have been submitted to OS Hub. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /sectors/
Use Case: GET /sectors/
Base URL: https://opensupplyhub.org/api/sectors/
Returns a list of suggested sectors submitted by sectors, sorted alphabetically. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /contributor-types/
Use Case: GET /contributor-types/
Base URL: https://opensupplyhub.org/api/contributor-types/
Returns a list of contributor types available in OS Hub by value and display name, sorted alphabetically. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /parent-companies/
Use Case: GET /parent-companies/
Base URL: https://opensupplyhub.org/api/parent-companies/
Returns a list of parent companies contributed to OS Hub by value and display name, sorted alphabetically. There are no available parameters for this endpoint.
Sample Response:
Endpoint: /facility-processing-types/
Use Case: GET /facility-processing-types/
Base URL: https://opensupplyhub.org/api/facility-processing-types/
Returns an array of objects with “facilityType” set to the name of a facility type and “processingTypes” set to an array of processing types associated with that facility type. There are no available parameters for this endpoint.
Sample Response:
