ePATHogen API guide

From Public Health Agency of Canada

Using this API will allow you to get the data about the pathogens you want in your application. It is provided as a search, the same search that the application uses.

Search API

URL:

https://health.canada.ca/en/epathogen/search

HTTP method:

GET

Description

This search function will return the list of agent with all the details.

Arguments

term

Default: empty string

The term you want to search (ex: the name of the pathogen). When an empty string is passed, the full list of pathogen will be returned

format

Default: 'json'

Specify the format you want the information to be returned. The default value is JSON, but you can specify csv to return a CSV file. You may also specify csvweb to receive a human readable CSV file (the columns keys are human readable instead of IDs).

lang

Default: 'en'

The language you want the results in. Accepted values are en and fr.

agentType

Default: empty array

An array of agent type to be returned. Agent types are bacteria, fungus, prion, virus, etc. Values are separated by 'or' meaning that if you select two values, the system will return agents that are in either group, not only agents found both.For a list of valid values, please see the autocomplete section below.

humanRisk

Default: 'en'

An array of human risk group classification to be returned. Values are separated by 'or' meaning that if you select two values, the system will return agents that are in either group, not only agents found both. For a list of valid values, please see the autocomplete section below.

animalRisk

Default: 'en'

An array of animal risk group classification to be returned. Values are separated by 'or' meaning that if you select two values, the system will return agents that are in either group, not only agents found both. For a list of valid values, please see the autocomplete section below.

terrestrialAnimalPathogenUnderCFIAAuthority

Default: -1

Should the results only include the pathogen of type terrestrial animal under CFIA authority. For a list of valid values, please see the autocomplete section below.

securitySensitiveBiologicalAgent

Default: -1

Should the results only include the pathogen with sensitive security. For a list of valid values, please see the autocomplete section below.

idAsKey

Default: true

Boolean. If set to true, a JSON object will be returned with the id of the agent as the object keys. If set to false, a normal JSON array (no keys) will be returned. This is only used with returning JSON.

Search return

If the format requested is json, the information will be returned in the formats described below. If using the csv format, the columns are the same results object described below except that the altNames is not an object but a coma separated list of alternate names. If using the csvweb format, all the ID columns and some of the dates columns were removed. This last format is mostly presented as human readable.

options

Object containing all the search parameter that was received by the server.

results

If the idAsKey argument is true, then results is an object with the keys as the ID of each agent. The ID is UUID format (ex: 643dde10-6394-e511-814c-000c2902c387). If it was set to false, results is a simple array of the agents. Each agent is an object with the following keys:

id

A unique UUID for the agent.

name

The name of the agent, alternate names can be found in the altName key.

type

Display ready/human readable type of the agent in the language requested.

typeId

The specific ID for this agent type.

HumanRiskGroup

Display ready/human readable value of the human risk group classification, or regulated/non-regulated human toxin

HumanRiskGroupId

The specific ID for this human risk group classification.

AnimalRiskGroup

Display ready/human readable value of the animal risk group classification, or regulated/non-regulated animal toxin

AnimalRiskGroupId

The specific ID for this animal risk group classification.

SecuritySensitiveBiologicalAgent

Display ready/human readable value of the security sensitive biological agent. Additional security requirements apply.

SecuritySensitiveBiologicalAgentId

The specific ID for this SecuritySensitiveBiologicalAgent value.

TerrestrialAnimalPathogenUnderCFIAAuthority

Display ready/human readable value of if the agent is a terrestrial animal pathogen under the authority of the Canadian Food Inspection Agency. Pathogens affecting aquatic animals, bees, and plants are also regulated by the CFIA.

TerrestrialAnimalPathogenUnderCFIAAuthorityId

The specific ID for this TerrestrialAnimalPathogenUnderCFIAAuthority value.

ContainmentLevel

Display ready/human readable value of the containment level needed for this agent.

ContainmentLevelId

The specific ID for this ContainmentLevel value.

ConsiderationsForContainment

If the agent has special consideration for containment, it will be noted in this field.

AgentCreatedDate

The date when this agent was created in our database.

AgentLastModifiedDate

The date when this agent was last modified in our database.

RiskAssessmentCreatedDate

The date the risk assessment was created in our database.

RiskAssessmentLastModifiedDate

The date when the risk assessment for this agent was last modified.

orderValue

Internal value used for ordering the list of agent. If the name of the agent match exactly the search term, the value is 100. If the agent name starts with the search term, this value is 85. If the full term is present in the name (ex: the term encephalopathy in the name Bovine spongiform encephalopathy agent), the value is 75. If the term begins a word in the name, the value would be 50. If the term ends a word, the value is 25. Finally, if the value is found as part of a word in the name, the value will be 10

altName

An array of all, if any, alternative name for this agent. Each element of this array is composed of:

altId

The specific UUID for this alternative agent name.

name

The alternative name of this agent.

latestDateModified

The most recent date from this list AgentCreatedDate, AgentLastModifiedDate, RiskAssessmentCreatedDate and RiskAssessmentLastModifiedDate

Autocomplete

URL:

https://health.canada.ca/en/epathogen/autocomplete

HTTP method:

GET

Description

This URL will return a JSON list of values/labels for each elements that can be filled. You can use it to fill form for the end user or use it as a autocomplete list.

Arguments

lang

Default: 'en'

The language you want the results in. Accepted values are 'en' and 'fr'.

returnNames

Default: true

If true, all the names of agent in the database will be returned (used for autocomplete). If false, will only return all other information, this can save some bandwidth if you will not use it.

Autocomplete return (JSON)

names

Array of every name and alternate name of agent in the database. This can be used for an auto-complete when the user type a search term.

types

Array of object containing value and label of every type of agent in the database.

humanRisk

Array of object containing value and label of valid human risk group classifications.

animalRisk

Array of object containing value and label of valid animal risk group classifications.

terrestrialAnimalPathogen

Array of object containing value and label of possible value for terrestrialAnimalPathogen.

securitySensitive

Array of object containing value and label of possible value for securitySensitive.