Skip to content

19andMe API documentation

Jump to bottom
Emma Pendl-Robinson edited this page Mar 23, 2023 · 45 revisions

Home

Hello, we want to help you get started with using 19andMe API!

The 19andMe API enables programmatic access to the COVID-19 risk calculator in unique and advanced ways. Use it to estimate COVID-19 risks, get county-level underreporting factor, identify segments of the population with high vulnerability, and so much more.

On March 31, 2023, the 19andMe API was discontinued and is no longer being maintained. For demonstration purposes, the tool returns risk scores as of April 6th, 2022.

Endpoint URL

For EU: https://eu-api.covid19.mathematica.org/score

For USA: https://us-api.covid19.mathematica.org/score

Authentication and rate limits

Email Mathematica to get an API key.

Rate limit: 500 requests per 15-minute window

Query parameters

Name Type Description Potential values Validations
zip REQUIRED str Zip code,
  • for US: 5 digits zip codes,
  • for BE: 4 digits postal codes
  • for US: 00001 - 99999
  • for BE: 0001-9999
  • for US: str that is five digits long, if not five digits long, zfill(5)
  • for BE: str that is four digits long
fips OPTIONAL str FIPS county code maybe used instead of the param zip,
  • for US: 5 digit state county FIPS code,
  • for BE: 5 digit municipality code
 00001 - 99999
  • Only one of 'zip' or 'fips' should be provided, not both.
  • str that is five digits long, if not five digits long, zfill(5)
country OPTIONAL str 2 letter county code for requested location, if parameter is not provided, the default value is "us" "us", "be" country code must be "us" or "be"
age REQUIRED int Age 0 - 122
  • is a numeric and not missing if not, return message “Age must be an integer.”
  • age > = 0 if not, return error message “Age can't be negative.”
  • age < 123 if not, return “According to the Guinness World Records, age must be smaller than 123.”
sex REQUIRED str Sex assigned at birth "male", "female", "sex_other" can only be one of the three potential values
symptoms OPTIONAL list of strings List of symptoms ['loss_smell_taste', 'severe_cough', 'severe_fatigue', 'loss_appetite', 'other']

(formerly: [“is_loss_smell_taste”, “is_cough”, “is_fatigue”, “is_skip_meal”, “is_other”])		 can only be one of the five potential values
conditions OPTIONAL list of strings List of pre-existing conditions ['renal_disease', 'cardiovascular_disease', 'diabetes', 'hypertension', 'smoking', 'immunocompromised', 'lung_disease', 'obesity', 'pregnancy', 'cancer', 'sickle_cell', 'downsyndrome','other']

(formerly: [“is_renal”, “is_cvd”, “is_diabetes”, “is_hyper”, “is_smoker”, “is_immune”, “is_lung”, “is_obesity”, “is_other”])
  • can only be one or more of the 13 potential values.
direct_contacts REQUIRED

(formerly 'nppl')		 int Number of people you come into close contact with in a week 0 - 100 if live_w_others is TRUE, direct_contacts >=1
live_w_others REQUIRED

(formerly 'is_roommate')		 str Do you live with other people? "True", "False"
indirect_contacts REQUIRED

(formerly 'nppl2')		 int Number of people your housemates come into close contact with in a week 0 - 100
hand REQUIRED str Do you wash your hands per CDC guidance? "True", "False"
ppe REQUIRED str Do you wear personal protection equipment per CDC guidance? "True", "False"
vaccine OPTIONAL str Name of COVID-19 vaccine received, if any "pfizer","moderna", "johnsonandjohnson"/"jandj", "astrazeneca" Can only be one of the potential values (not case sensitive, spaces allowed)
months_last_vaccinationOPTIONAL str Number of months since most recent COVID-19 vaccine
Abbreviations:
  • "lt_1mo" = Within one month
  • "btw_1_6mo" = 1-6 months ago
  • "gt_6mo" = More than 6 months ago
 "lt_1mo", "btw_1_6mo", "gt_6mo" must be one of the calculator's recognized values: "lt_1mo", "btw_1_6mo", "gt_6mo"
days_since_last_dose DEPRECATED int Deprecated as of release 1.16.0. Please use months_last_vaccination instead.
Number of days since most recent dose of vaccine		 0-∞ must be a positive integer
activities_highOPTIONAL int Count of the high-risk activities the user participated in the previous week.
The 19andMe App lists the following high-risk activities:
  • Indoor restaurant or bar
  • Nightclub/music concert/movie theater/gym
  • Sports stadium
  • Religious services (including weddings and funerals)
  • Team sports (e.g. basketball, football)
  • Visiting nursing home or hospital
 0-∞ must be a positive integer
activities_mediumOPTIONAL int Count of the medium-risk activities the user participated in the previous week.
The 19andMe App lists the following medium-risk activities:
  • In person work or school
  • Indoor busy or crowed activities (e.g. casino, shopping mall, salon)
  • Public transportation/airplane
  • Overnight stay at a hotel
  • Outdoor dining
  • Seeing doctor or dentist
 0-∞ must be a positive integer
activities_lowOPTIONAL int Count of the low-risk activities the user participated in the previous week.
The 19andMe App lists the following low-risk activities:
  • Indoor socially distanced activities (e.g. grocery store, library, museum)
  • Outdoor socially distanced activities
 0-∞ must be a positive integer
exercise_levelOPTIONAL str On average how many minutes per week do you engage in moderate to strenuous exercises (like brisk walking)? Abbreviations:
  • "lte_10mpw" = less than or equal to 10 minutes per week
  • "btw_11_149mpw" = between 11 and 149 minutes per week
  • "gte_150mpw" = greater that or equal to 150 minutes per week
 "lte_10mpw", "btw_11_149mpw", "gte_150mpw" Exercise level must be one of the calculator's recognized exercise level:['lte_10mpw', 'btw_11_149mpw', 'gte_150mpw'].
calc_dateOPTIONAL str Users can input a prior date to run the risk score calculation based on historical COVID-19 data.
If no date is provided, the most recent date is used.		 "today" or date formatted as %m/%d/%Y The calc_date parameter only accepts values between 04/02/2020 and today, inclusive.

Example requests

{
    "zip": "02120",
    "country": "us",
    "age": 29,
    "sex": "female",
    "symptoms": [],
    "direct_contacts": 1,
    "live_w_others": 'True',
    "indirect_contacts": 10,
    "hand": 'True',
    "ppe": 'True',
    "conditions": ['renal_disease'],
    "vaccine": "pfizer",
    "months_last_vaccination": "btw_1_6mo",
    "activities_high": 0,
    "activities_medium": 2,
    "activities_low": 5, 
    "exercise_level": 'btw_11_149mpw',
    "calc_date": "08/10/2021" 
}

Example responses

An example of the output for a zipcode with one associated county is:

{
    "results": [
        {
            "fips": "25025",
            "population": 803907.0,
            "country": "us",
            "latest_day": "08/09/2021",
            "underreport_factor": 1.6066576,
            "county": "Suffolk County, MA",
            "cumulative_cases": 95694,
            "cases_past14d": 1625,
            "est_current_sick": 2610.8186,
            "exposure_risk": 0.0002874611726409835,
            "sympt_covid_risk": 0.0,
            "hosp_risk": 0.020484539093159827,
            "icu_risk": 0.003399280341842611,
            "death_risk": 0.00047996832743515624,
            "vulnerability_risk": 0.024363787762437594,
            "risk_score": 33.81215512108318,
            "flu_risk_natl_avg": 0.004146874511131606,
            "risk_reduction_handwash": 0.5498418963550474,
            "risk_reduction_ppe": 0.6798045264026041,
            "vaccine_reduction": {
                "infection_efficacy": 0.7986,
                "hosp_efficacy": 0.4128,
                "icu_efficacy": 0.4128,
                "death_efficacy": 0.4896
            },
            "name": "Suffolk County, MA",
            "n_case_today": 95694,
            "moving_casecount": 1625,
            "est_unreported_sick": 2610.8186,
            "score": 33.81215512108318,
            "prob_flu": 0.004146874511131606,
            "risk_hand_delta": 0.5498418963550474,
            "risk_ppe_delta": 0.6798045264026041
        }
    ],
    "disclaimer": "Your use of this tool is subject to these Terms of Use: https://19andme-pub-0812304701987.s3.amazonaws.com/COVID-19+Risk+Calculator+Terms+of+Use+-+042220.pdf THE INFORMATION PROVIDED BY THIS TOOL IS NOT MEDICAL ADVICE AND CANNOT BE USED TO DIAGNOSE OR TREAT ANY MEDICAL CONDITION."
}

An example of the output for a zipcode with two associated counties is:

{
    "results": [
        {
            "fips": "25021",
            "population": 706775.0,
            "country": "us",
            "latest_day": "08/09/2021",
            "underreport_factor": 2.3132255,
            "county": "Norfolk County, MA",
            "cumulative_cases": 56399,
            "cases_past14d": 920,
            "est_current_sick": 2128.16746,
            "exposure_risk": 0.00026644376403562144,
            "sympt_covid_risk": 0.0,
            "hosp_risk": 0.020484539093159827,
            "icu_risk": 0.003399280341842611,
            "death_risk": 0.00047996832743515624,
            "vulnerability_risk": 0.024363787762437594,
            "risk_score": 33.262594578038616,
            "flu_risk_natl_avg": 0.004146874511131606,
            "risk_reduction_handwash": 0.5498534559297804,
            "risk_reduction_ppe": 0.6798188182404558,
            "vaccine_reduction": {
                "infection_efficacy": 0.7986,
                "hosp_efficacy": 0.4128,
                "icu_efficacy": 0.4128,
                "death_efficacy": 0.4896
            },
            "name": "Norfolk County, MA",
            "n_case_today": 56399,
            "moving_casecount": 920,
            "est_unreported_sick": 2128.16746,
            "score": 33.262594578038616,
            "prob_flu": 0.004146874511131606,
            "risk_hand_delta": 0.5498534559297804,
            "risk_ppe_delta": 0.6798188182404558
        },
        {
            "fips": "25025",
            "population": 803907.0,
            "country": "us",
            "latest_day": "08/09/2021",
            "underreport_factor": 1.6066576,
            "county": "Suffolk County, MA",
            "cumulative_cases": 95694,
            "cases_past14d": 1625,
            "est_current_sick": 2610.8186,
            "exposure_risk": 0.0002874611726409835,
            "sympt_covid_risk": 0.0,
            "hosp_risk": 0.020484539093159827,
            "icu_risk": 0.003399280341842611,
            "death_risk": 0.00047996832743515624,
            "vulnerability_risk": 0.024363787762437594,
            "risk_score": 33.81215512108318,
            "flu_risk_natl_avg": 0.004146874511131606,
            "risk_reduction_handwash": 0.5498418963550474,
            "risk_reduction_ppe": 0.6798045264026041,
            "vaccine_reduction": {
                "infection_efficacy": 0.7986,
                "hosp_efficacy": 0.4128,
                "icu_efficacy": 0.4128,
                "death_efficacy": 0.4896
            },
            "name": "Suffolk County, MA",
            "n_case_today": 95694,
            "moving_casecount": 1625,
            "est_unreported_sick": 2610.8186,
            "score": 33.81215512108318,
            "prob_flu": 0.004146874511131606,
            "risk_hand_delta": 0.5498418963550474,
            "risk_ppe_delta": 0.6798045264026041
        }
    ],
    "disclaimer": "Your use of this tool is subject to these Terms of Use: https://19andme-pub-0812304701987.s3.amazonaws.com/COVID-19+Risk+Calculator+Terms+of+Use+-+042220.pdf THE INFORMATION PROVIDED BY THIS TOOL IS NOT MEDICAL ADVICE AND CANNOT BE USED TO DIAGNOSE OR TREAT ANY MEDICAL CONDITION."
}

API endpoint outputs

Name Type Description
fips str FIPS code that matches the zip code
population int Population of the county
county str County name
latest_day date The most recent date for date for the selected county
case_past14d int Number of new cases in the past 14 days

(formerly 'moving_casecount')
cumulative_cases int Total confirmed cases

(formerly 'n_case_today')
underreport_factor num County-level under reporting factor
est_current_sick num Estimated total active cases, including those not officially reported

(formerly est_unreported_sick)
exposure_risk num Estimated probability of catching COVID-19 through community transmission
hosp_risk num Estimated risk of hospitalization conditioning on COVID-19 infection
icu_risk num Estimated risk of requiring an ICU conditioning on COVID-19 infection
death_risk num Estimated mortality risk conditioning on COVID-19 infection
vulnerability_risk num The sum of risk of hospitalization, risk of requiring ICU, and risk of dying
sympt_covid_risk num Estimated probability that you have symptomatic COVID-19 given the self-reported symptoms
risk_score num COVID-19 risk score, a semi-quantitative score of 1 to 100.

(formerly 'score')
flu_risk_natl_avg num Probability of an average American catching flu during the flu season
risk_reduction_handwash num Percent lower risk of being exposed to COVID-19 by following hand hygiene guidelines
risk_reduction_ppe num Percent lower risk of being exposed to COVID-19 by wearing PPE
vaccine_reduction num Percent lower risk from vaccine
disclaimer str Disclaimer

Change Log

The 19andMe API Change Log is available online within the 19andMe App on the "Change Log" tab.

For more information, email Mathematica

19andMe API

Clone this wiki locally