Use of the Project Tycho API requires an API key. Registered users may obtain their API key on the user Profile page.
The following queries allow users to retrieve available values for each variable in the Project Tycho Pre-compiled data format, except for PeriodStartDate and PeriodEndDate. Data is returned in CSV format. Where filters are available, variable names are case-sensitive.
Returns ConditionName, ConditionSNOMED
Retrieve full listing of all available condition information:
https://www.tycho.pitt.edu/api/condition?apikey=APIKEY
Optional filters are available on either of the two returned variables.
Example – Retrieve ConditionSNOMED for a known ConditionName:
https://www.tycho.pitt.edu/api/condition?apikey=APIKEY&ConditionName=Measles
Returns CountryISO, CountryName
Retrieve full listing of all available admin1 location information: https://www.tycho.pitt.edu/api/country?apikey=APIKEY
Optional filters are available on either of the two returned variables.
Example – Retrieve CountryISO for a known CountryName:
https://www.tycho.pitt.edu/api/country?apikey=APIKEY&CountryName=UNITED STATES OF AMERICA
Returns CountryISO, CountryName, Admin1ISO, Admin1Name
Retrieve full listing of all available admin1 location information: https://www.tycho.pitt.edu/api/admin1?apikey=APIKEY
Optional filters are available on any of the four returned variables.
Example 1 – Limit to admin1 information for the United States:
https://www.tycho.pitt.edu/api/admin1?apikey=APIKEY&CountryISO=US
Example 2 – Retrieve Admin1ISO for a known Admin1Name:
https://www.tycho.pitt.edu/api/admin1?apikey=APIKEY&CountryISO=US&Admin1Name=Pennsylvania
Returns CountryISO, CountryName, Admin1ISO, Admin1Name, Admin2Name
Retrieve full listing of all available admin1 location information: https://www.tycho.pitt.edu/api/admin2?apikey=APIKEY
Optional filters are available on any of the five returned variables.
Example 1 – Limit to admin2 information for the United States:
https://www.tycho.pitt.edu/api/admin2?apikey=APIKEY&CountryISO=US
Example 2 – Limit to admin2 information in Pennsylvania, US:
https://www.tycho.pitt.edu/api/admin1?apikey=APIKEY&CountryISO=US&Admin1ISO=US-PA
Returns CountryISO, CountryName, Admin1ISO, Admin1Name, Admin2Name, CityName
Retrieve full listing of all available admin1 location information: https://www.tycho.pitt.edu/api/city?apikey=APIKEY
Optional filters are available on any of the six returned variables.
Example 1 – Limit to city information for the United States:
https://www.tycho.pitt.edu/api/city?apikey=APIKEY&CountryISO=US
Example 2 – Limit to city information in Pennsylvania, US:
https://www.tycho.pitt.edu/api/city?apikey=APIKEY&CountryISO=US&Admin1ISO=US-PA
Returns PathogenName, PathogenTaxonID
Retrieve full listing of all available admin1 location information: https://www.tycho.pitt.edu/api/pathogen?apikey=APIKEY
Optional filters are available on any of the two returned variables.
Example – Retrieve PathogenTaxonID for a known PathogenName:
https://www.tycho.pitt.edu/api/pathegen?apikey=APIKEY&PathogenName= Anaplasma phagocytophilum
Returns AgeRange
Retrieve full listing of all available AgeRange: https://www.tycho.pitt.edu/api/agerange?apikey=APIKEY
No filters are available.
Returns Subpopulation
Retrieve full listing of all available Subpopulation: https://www.tycho.pitt.edu/api/subpopulation?apikey=APIKEY
No filters are available.
Returns Fatalities
Retrieve full listing of all available Fatalities: https://www.tycho.pitt.edu/api/fatalities?apikey=APIKEY
No filters are available.
Returns PartOfCumulativeCountSeries
Retrieve full listing of all available PartOfCumulativeCountSeries: https://www.tycho.pitt.edu/api/cumulative?apikey=APIKEY
No filters are available.
Returns DiagnosisCertainty
Retrieve full listing of all available DiagnosisCertainty: https://www.tycho.pitt.edu/api/diagnosiscertainty?apikey=APIKEY
No filters are available.
Returns PlaceOfAcqusition
Retrieve full listing of all available PlaceOfAcqusition: https://www.tycho.pitt.edu/api/placeofacquisition?apikey=APIKEY
No filters are available.
Returns SourceName
Retrieve full listing of all available SourceName: https://www.tycho.pitt.edu/api/sourcename?apikey=APIKEY
No filters are available.
Data queries allow users to retrieve a filtered subset of Project Tycho data, similar to what is available from the “Compile Your Own” Search interface. Data is returned in the Project Tycho Format.
Filtering is available on any of the variables included in the Project Tycho Format. The variable names are case-sensitive and must match the case used in the column headings in the ProjectTycho Format.
Each query must specify both a condition and a location. Users can specify a condition and location in multiple ways.
For condition, select a value for one of: ConditionName or ConditionSNOMED
For location, select a value for at least one of: CountryISO, CountryName, Admin1ISO, Admin1Name, Admin2Name, CityName
Any remaining variables in the Project Tycho format can be optionally included. Date ranges can be specified using PeriodStartDate and PeriodEndDate, and the operators =, >=, and <= . Dates must always be specified in the format YYYY-MM-DD.
limit – how many rows of results to retrieve. By default, the API query retrieves a limit of 5000 rows per call. Maximum limit is 20,000.
offset – for paging of results. For example, given a limit of 5000, specifying offset=5000 will return results starting at row 5001 (i.e., page 2 of the results). If the offset is greater than the number of data rows, “No results” will be returned.
1a. Retrieve counts of Measles in Pennsylvania, United States that are not cumulative and not fatalities (will retrieve first 5000 results):
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Measles&CountryISO=US&Admin1ISO=US-PA&Fatalities=0&PartOfCumulativeCountSeries=0
1b. Retrieve page 2 (next 5000 results) of the query specified in Example 1a:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Measles&CountryISO=US&Admin1ISO=US-PA&Fatalities=0&PartOfCumulativeCountSeries=0&offset=5000
2a. Retrieve counts of Dengue fatalities in Laos during 2000-2003:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Dengue&CountryName=LAO PEOPLE'S DEMOCRATIC REPUBLIC&PeriodStartDate>=2000-01-01&PeriodEndDate<=2003-12-31
2b. Retrieve counts of Dengue fatalities in Laos starting on February 1, 2000:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Dengue&CountryName=LAO%20PEOPLE'S%20DEMOCRATIC%20REPUBLIC&PeriodStartDate=2000-02-01
3. Retrieve counts of Dengue fatalities and non-fatalities in Argentina reported on the Pan American Health Organization website:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Dengue&CountryISO=AR&SourceName=Pan American Health Organization website
4a. Retrieve first 10,000 counts of Measles in the state of New York, United States that are not fatalities:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Measles&CountryISO=US&Admin1ISO=US-NY&Fatalities=0&limit=10000
4b. Retrieve next 10,000 counts of Measles in the state of New York, United States that are not
fatalities:
https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Measles&CountryISO=US&Admin1ISO=US-NY&Fatalities=0&limit=10000&offset=10000
Download results to a file:
#!/usr/bin/python
import urllib.request
url =
"https://www.tycho.pitt.edu/api/query?apikey=APIKEY&ConditionName=Dengue&CountryName=LAO
PEOPLE'S DEMOCRATIC REPUBLIC&PeriodStartDate>=2000-01-01&PeriodEndDate<=2003-12-31"
outfile = open(“outfile.csv”,”w”)
req = urllib.request.urlopen(url)
content = req.read()
outfie.write(content.decode(“utf8”)
outfile.close()
Load results into a data frame:
> California_gonorrhea <- read.table('https://www.tycho.pitt.edu/api/query?C
ountryISO=US&ConditionName=Gonorrhea&Fatalities=0&Admin1Name=California&apikey=YOURAPIKEY',
header=TRUE, sep=",")