Public web API examples

2024-10-19

Accessing the Drug Shortages public API is possible using a variety of digital tools. The following code provides examples for some of these.

Python Requests

The Requests library is a popular option for accessing web services in the Python language. 

Setup

Install the library by running this command in a Terminal window.

python -m pip install requests

At the top of the Python file, be sure to import the library.

import requests

Logging in

Before any calls to the API can be made, it is necessary to retrieve an access token linked to your account. The following code block demonstrates how to make a login request and save the resulting auth-token if the request succeeds.

data = {'email': '<my email>', 'password': '<my password>'}
url = 'https://www.drugshortagescanada.ca/api/v1/login'
r = requests.post(url, data=data)
if r.status_code == 200:
    authToken = r.headers['auth-token']

Be sure to replace the <my email> and <my password> data with your actual values. Note that the API supports both JSON content with json=data and conventional URL encoding with data=data. A proper script should handle an invalid status code and store the authToken for future requests.

Searching for reports

With the authToken value available, it is now possible to search the database for reports of interest. The following code block shows how to make this request.

parameters = {'term': '<company name>', 'limit': 50, 'offset': 0}
headers = {'auth-token': authToken}
url = 'https://www.drugshortagescanada.ca/api/v1/search'
r = requests.get(url, headers=headers, params=parameters)
if r.status_code == 200:
    responseJson = r.json()
    reports = responseJson['data']

Be sure to change the <company name> value to the search term of interest. If the goal is to retrieve the entire report database for custom analysis, it is recommended that the monthly data extract be used instead. The API is optimized for reviewing a smaller subset of reports, like for individual companies or specific DINs.

Note the inclusion of the limit and offset variables in the parameter data. By adjusting the offset value, it is possible to page through the results in subsequent requests. Here is an example of requesting data on "page 3".

parameters = {'term': '<company name>', 'limit': 50, 'offset': 150}

By repeating the requests until the page value equals total_pages, it is possible to step through the results. 

The API provides additional options for sorting or filtering the responses. Here are some examples of them.

parameters = {'term': '<company name>', 'limit': 50, 'offset': 0, 'orderby': 'brand_name', 'order': 'asc'}

This will sort the data alphabetically by brand name.

parameters = {'term': '<company name>', 'limit': 50, 'offset': 0, 'filter_status': 'resolved'}

This will filter the results to reports that have been marked resolved.

Additional sorting and filtering options are available on the main API documentation page.

Postman collection

Postman is an API development tool that can provide a collection of request examples. We have created a collection that includes the following demonstrations:

This collection can be downloaded here. You will need to create environment variables to make the initial requests work. These include:

cURL

The fastest way to verify the parameters and URL of your request is to use the command line tool cURL. This is present by default on Mac and Linux systems and can be installed to Windows if it isn't already bundled.

Run the following command in the terminal window and simply substitute the email and password as necessary.

curl 'https://www.drugshortagescanada.ca/api/v1/login' -D - -X POST --data "email=<email>&password=<password>"

The output should be a JSON bundle containing the requested user account and response headers containing a login token with the -D - option.

Other tools

There are other ways to access the API -- potentially including Microsoft Excel -- but these require more details about the desired output. For these situations, please get in touch with the support team using the Contact page.