Public API Access

2018-09-18

The website now provides public access to the drug shortage and discontinuation report database through an Application Programming Interface (API). The API allows developers to access that information through a standard REST web API by returning JSON content for use in their own applications. Provided below are the endpoints available.

Access settings

Base URL https://www.drugshortagescanada.ca/api/v1
Content-type application/json
Parameter encoding application/x-www-form-urlencoded
Authorization header auth-token

 

 

 

Response formats

All requests return JSON text in one of the following formats:

Error response

An invalid request will include an error object containing English and French explanations. Example:

{"error" : {"en" : "", "fr" : ""}}

List response

A list response, like the search query, will return paginated data in the following object:

Object response

Requests returning a single object will provide a standard JSON object.

Rate limiting

For availability reasons, each account is rate limited to a maximum of 1000 requests per hour. Any requests above that rate will return a 429 response code. If you wish to have a higher rate, please use the contact form to indicate your usage requirements.

Endpoints

Authentication requires a valid web account, which in turn requires a verified email. Each subsequent request will require using an authorization header

Login

Path login
Authorization header none
Method POST
Parameters
  • email
  • password
Response codes
  • 200 = Request OK
  • 400 = Bad request; check email/password
  • 403 = Account not verified
Response data

If the request is invalid, an error object is returned.

A valid request will return an object containing these keys:

  • user = the logged in user data

A valid user token will be returned in the auth-token header, with relevant expiry date info in the expiry-date key.

The login request provides an access token needed by other endpoints. It accepts the email/password combination used on the website.

Report search

Path search
Authorization header auth-token : {user access token}
Method GET
Parameters
  • orderby = specify the column to sort the results by
    • id = report ID
    • company_name = the company associated with the report
    • brand_name = the drug associated with the report
    • status = the current status of the report
    • type = the type of report (shortage or discontinuation)
    • updated_date = the date of the last change to the report
  • order = asc for ascending; desc for descending
  • filter_status = only return reports of the given status
  • term = main text search value
  • din
  • report_id
Response codes
  • 200 = Request OK
  • 400 = Bad request; invalid parameters
  • 403 = Invalid user token
Response data

If the request is invalid, an error object is returned.

A valid request will return a list object in the format noted above.

This main search query will return shortage and discontinuation reports according to the provided parameters.

Single shortage report

Path shortages/{shortage report ID}
Authorization header auth-token : {user access token}
Method GET
Parameters none
Response codes
  • 200 = Request OK
  • 403 = Invalid user token
  • 400 = The report is unavailable
  • 404 = The report is not found
Response data

If the request is invalid, an error object is returned.

A valid request will return a single detailed report object.

This request will provide a more detailed snapshot of the report object from the list.

Single discontinuation report

Path discontinuances/{discontinuation report ID}
Authorization header auth-token : {user access token}
Method GET
Parameters none
Response codes
  • 200 = Request OK
  • 403 = Invalid user token
  • 400 = The report is unavailable
  • 404 = The report is not found
Response data

If the request is invalid, an error object is returned.

A valid request will return a single detailed report object.

This request will return a more detailed snapshot of the selected report.