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:

total = total objects matched by the request
limit = the maximum number of objects returned in the single request
offset = the starting index of the response (defaults to 0)
page = the current page according to the limit and offset values
remaining = the number of objects available after the current page (used for infinite list loading)
data = an array of the requested data
total_pages = the total number of pages available the request

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 resolved anticipated_shortage active_confirmed avoided_shortage discontinued 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.