API Reference

Welcome to the documentation for our current API endpoints. Our deprecated (but still supported) API endpoints can be found here, although we encourage you to use the ones listed below.


Account & Profile
Genetic Data
Report
  • Requires OAuth= requires OAuth token

Some 23andMe API endpoints return non-user-specific reference data and provide unrestricted access, while others return user-specific data and thus require the user's authorization.

Authorization

API requests for profile-level data use OAuth 2.0 bearer tokens over SSL in the Authorization header (read through our authorization reference to find out how to get a token).

Your token grants access to data from the customer who authorized it. For example: 

curl "https://api.23andme.com/3/account/" -H "Authorization: Bearer 081239h0f71hf"

For development, you can skip the OAuth flow by using a demo token, demo_oauth_token, to fetch sample data. Example: 

curl "https://api.23andme.com/3/account/" -H "Authorization: Bearer demo_oauth_token"

Data returned for the demo token is not linked to a real account and is for testing purposes only.

Enveloping

Every endpoint returning a list of resources is "enveloped" to include a link for the next "page" of data, if it exists. Example: 

    {
        "data": [resources...],
        "links": {
            "next": "https://api.23andme.com/3/marker/?accession_id=NC_000002.11&start=47807&end=48607"
        }
    }

Though the next link may be null if pagination is not supported or there are no additional pages, lists of resources will always be enveloped in this manner.

Account & Profile Endpoints


Account Object

A user signs into their account. An account may own one or more profiles.

id
string		 the unique id associated with the account
first_name
string		 the first name of the account owner
  • null if no names scope
last_name
string		 the last name of the account owner
  • null if no names scope
email
string		 the email of the account owner
  • null if no names scope
profiles
list		 a list of profile ids (or objects - see the include parameter) owned by this account
endpoint example call and result

GET /3/account/

parameters:
  • include string, optional
Requires OAuth requires token Back To Top ↑

Returns a list containing the user account associated with the token. 

curl "https://api.23andme.com/3/account/" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "data": [
        {
            "id": "demo_account_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "email": "nobody+erinmendel@23andme.com",
            "profiles": [
                {
                    "id": "demo_profile_id"
                }
            ]
        }
    ],
    "links": {
        "next": null
    }
}

The optional include parameter can be set to profiles to expand the list of profile ids into profile objects:

curl "https://api.23andme.com/3/account/?include=profiles" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "data": [
        {
            "id": "demo_account_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "email": "nobody+erinmendel@23andme.com",
            "profiles": [
                {
                    "id": "demo_profile_id",
                    "first_name": "Erin",
                    "last_name": "Mendel",
                    "is_genotyped": true,
                    "is_ancestry_only": false,
                    "profile_image": null
                }
            ]
        }
    ],
    "links": {
        "next": null
    }
}
required scope
basic (required)
names (optional)
email (optional)
profile:image (optional)
endpoint example call and result

GET /3/account/account_id/

parameters:
  • include string, optional
Requires OAuth requires token Back To Top ↑

Returns the account for the specified account_id (will 403 if the account_id is not the one authorized for the token). 

curl "https://api.23andme.com/3/account/demo_account_id/" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "id": "demo_account_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "email": "nobody+erinmendel@23andme.com",
    "profiles": [
        {
            "id": "demo_profile_id"
        }
    ]
}

The optional include parameter can be set to profiles to expand the list of profile ids into profile objects:

curl "https://api.23andme.com/3/account/demo_account_id/?include=profiles" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "id": "demo_account_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "email": "nobody+erinmendel@23andme.com",
    "profiles": [
        {
            "id": "demo_profile_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "is_genotyped": true,
            "is_ancestry_only": false,
            "profile_image": null
        }
    ]
}
required scope
basic (required)
names (optional)
email (optional)
profile:image (optional)
Profile Object

Each customer that has submitted a DNA sample has a profile. Each profile belongs to an account, which manages one or more profiles.

id
string		 the unique id associated with the profile
first_name
string		 the first name of the profile owner
  • null if no names scope
last_name
string		 the last name of the profile owner
  • null if no names scope
is_genotyped
boolean		 true if the profile has been genotyped
is_ancestry_only
boolean		 true if the profile is ancestry only
profile_image
string		 the url of the profile's image
  • null if no profile:image scope
  • null if profile has no image
endpoint example call and result

GET /3/profile/

parameters:

  • account_id string

Requires OAuth requires token Back To Top ↑

Returns a list of active profiles owned by the account. The account_id must be provided. 

curl "https://api.23andme.com/3/profile/?account_id=demo_account_id" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "data": [
        {
            "id": "demo_profile_id",
            "first_name": "Erin",
            "last_name": "Mendel",
            "is_genotyped": true,
            "is_ancestry_only": false,
            "profile_image": null
        }
    ],
    "links": {
        "next": null
    }
}
required scope
basic (required)
names (optional)
profile:image (optional)
endpoint example call and result

GET /3/profile/profile_id

Requires OAuth requires token Back To Top ↑

Returns a single profile for the given profile_id. 

curl "https://api.23andme.com/3/profile/demo_profile_id/" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "id": "demo_profile_id",
    "first_name": "Erin",
    "last_name": "Mendel",
    "is_genotyped": true,
    "is_ancestry_only": false,
    "profile_image": null
}
required scope
basic (required)
names (optional)
profile:image (optional)

Genetic Data Endpoints


Accession Object

23andMe uses the NCBI build 37 reference assembly. This is a set of standardized reference sequences where each accession corresponds to a chromosome (1-22, X, Y, & Mitochondrial). These endpoints will provide high-level reference data about the accession. For more in-depth exploration of the reference genome sequences, download seqseek and use Build 37.

id
string		 the accession id associated with the chromosome
chromosome
string		 the chromosome name (1-22, X, Y, and MT for mitochondrial)
length
integer		 the nucleotide length of the chromosome
endpoint example call and result

GET /3/accession/

parameters:

  • chromosome string, optional

Back To Top ↑

Returns a list of accessions available on 23andMe platforms. 

curl "https://api.23andme.com/3/accession/"
# JSON response:
{
    "data": [
        {
            "id": "NC_000001.10",
            "chromosome": "1",
            "length": 249250621
        },
        {
            "id": "NC_000002.11",
            "chromosome": "2",
            "length": 243199373
        },
        ...
    ],
    "links": {
        "next": null
    }
}

The optional chromosome parameter can be used to request the accession information for a single chromosome. If this parameter is provided, the next link will paginate through subsequent chromosomes.

curl "https://api.23andme.com/3/accession/?chromosome=1"
# JSON response:
{
    "data": [
        "id": "NC_000001.10",
        "chromosome": "1",
        "length": 249250621
    ],
    "links": {
        "next": https://api.23andme.com/3/accession/?chromosome=2
    }
}
endpoint example call and result

GET /3/accession/accession_id/

Back To Top ↑

Returns a single accession. 

curl "https://api.23andme.com/3/accession/NC_000001.10/"
# JSON response:
{
    "id": "NC_000001.10",
    "chromosome": "1",
    "length": 249250621
}
Marker Object

A marker is an identifier for multiple alleles that may exist at a genetic locus or region on a chromosome. Most of the markers will use the standardized NCBI rs# (reference SNP cluster id) that can be searched for in dbSNP, but others have "i-ids" (they start with i), which are internal to 23andMe and will not exist in dbSNP. Marker data correlates to the GRCh37 human reference genome.

id
string		 the primary id for the marker
alternate_ids
list		 alias ids for the marker
gene_names
list		 the display names of any genes at the marker
accession_id
string		 the unique id for the accession on which the marker is found
start
integer		 the chromosomal location of the start of the marker (counting from 0)
end
integer		 the chromosomal location of the end of the marker (counting from 0)
variants
list		 the different possible variants at this marker
endpoint example call and result

GET /3/marker/

required parameters:
  • id string (comma-separated values)
    • or
  • accession_id string
    • or
  • gene_name string
parameters for accession_id:
  • start integer, optional, default 0
  • end integer, optional, min 0, max/default is the last end position of the specified accession (length - 1)
pagination parameters:
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0
Back To Top ↑

Gets a list of genetic markers ordered by their start and end positions. Must use one of either id or gene_name or accession_id. Optionally, start and end parameters may only be used with accession_id.

The id parameter will return a list of markers that match those ids. It must be a string of comma-sparated values (no more than 10000). 

curl "https://api.23andme.com/3/marker/?id=rs10195681,i4001358"

The gene_name parameter will return a list of markers for that gene. 

curl "https://api.23andme.com/3/marker/?gene_name=ACTN3"

The accession_id parameter will return a list of markers on that chromosome. 

curl "https://api.23andme.com/3/marker/?accession_id=NC_012920.1"
# JSON response:
{
    "data": [
        {
            "id": "i4001200",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "C",
                    "platform_labels": ["ILMN_550Qv1_CUSTOMv2", "ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "T",
                    "platform_labels": ["ILMN_550Qv1_CUSTOMv2", "ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                }
            ]
        },
        {
            "id": "i4001110",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 6,
            "end": 7,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "A",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "G",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                }
            ]
        },
        {
            "id": "i4001358",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 8,
            "end": 9,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "A",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "G",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
                }
            ]
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/marker/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

When used with accession_id, the start parameter will load markers with end positions greater than or equal to this value. It must be greater than or equal to 0 and less than the length of the accession. It is 0 by default.

The end parameter will load markers with start positions less than or equal to end. It must be greater than or equal to 0 and less than the length of the specified accession. By default, it is the maximum end position of the specified accession.

Note that markers returned inside the specified start and end range do not have to be entirely contained within that range. Any overlapping markers will be returned.

offset and limit can be used to page through the markers. For example, limit=10 and offset=0 will return items 1-10. Furthermore, limit=10 and offset=10 will return items 11-20. 

curl "https://api.23andme.com/3/marker/?accession_id=NC_000015.9&start=75042285&end=75042485&limit=1&offset=0"
# JSON response:
{
    "data": [...],
    "links": {
        "next": "https://api.23andme.com/3/marker/?accession_id=NC_000015.9&start=75042285&end=75042485&limit=1&offset=1"
    }
}

In the above example, the next link contains an auto-incremented offset, which will return the next page of data. Each successive next link can be followed until it is null, in which case all results have been exhausted.

endpoint example call and result

GET /3/marker/marker_id/

Back To Top ↑

Returns a single marker. 

curl "https://api.23andme.com/3/marker/rs10195681/"
# JSON response:
{
    "id": "rs10195681",
    "alternate_ids": [],
    "gene_names": [],
    "accession_id": "NC_000002.11",
    "start": 18673,
    "end": 18674,
    "variants": [
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "A",
            "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
        },
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "C",
            "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"]
        }
    ]
}

In the event that there are multiple markers for the same set of variants, the other, "alias" marker ids of the requested marker will be listed under the alternate_ids attribute of the returned object. For example: 

curl "https://api.23andme.com/3/marker/i5019493/"
# JSON response:
{
    "id": "i5019493",
    "alternate_ids": ['i5035002'],
    ...
}

i5035002 is an alias for the requested marker, i5019493.

Profile Marker Object

In addition to the reference data provided by the marker object, the profile marker includes genetic data specific to a profile owner's genotype. Profile marker data correlates to the GRCh37 human reference genome.

. . . (same attributes as marker; instead of variant objects, variants will be a list of profile variants.)
is_genotyped
boolean		 true if the profile marker has been successfully genotyped for the profile (i.e. true if is_assayed is true and is_no_call is false).
is_assayed
boolean		 true if all profile variants were assayed for the profile marker
is_no_call
boolean		 true if the assay was performed and there were no results for any of the the profile marker's profile variants
endpoint example call and result

GET /3/profile/profile_id/marker/

required parameters:
  • id string (comma-separated values)
    • or
  • accession_id string
    • or
  • gene_name string
parameters for accession_id:
  • start integer, optional, default 0
  • end integer, optional, min 0, max/default is the last end position of the specified accession (length - 1)
pagination parameters:
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0
Requires OAuth requires token Back To Top ↑

For a user's profile, gets a list of profile markers ordered by their start and end positions.

Accepts the same request parameters as GET /marker. 

curl "https://api.23andme.com/3/profile/demo_profile_id/marker/?accession_id=NC_012920.1" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "data": [
        {
            "id": "i4001200",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "is_genotyped": true,
            "is_assayed": true,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "C",
                    "platform_labels": ["ILMN_550Qv1_CUSTOMv2", "ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": 0,
                    "is_assayed": true,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 2,
                    "end": 3,
                    "allele": "T",
                    "platform_labels": ["ILMN_550Qv1_CUSTOMv2", "ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": 1,
                    "is_assayed": true,
                    "is_no_call": false
                }
            ]
        },
        {
            "id": "i4001110",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 6,
            "end": 7,
            "is_genotyped": false,
            "is_assayed": false,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "A",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 6,
                    "end": 7,
                    "allele": "G",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                }
            ]
        },
        {
            "id": "i4001358",
            "alternate_ids": [],
            "gene_names": [],
            "accession_id": "NC_012920.1",
            "start": 8,
            "end": 9,
            "is_genotyped": false,
            "is_assayed": false,
            "is_no_call": false,
            "variants": [
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "A",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                },
                {
                    "accession_id": "NC_012920.1",
                    "start": 8,
                    "end": 9,
                    "allele": "G",
                    "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
                    "dosage": null,
                    "is_assayed": false,
                    "is_no_call": false
                }
            ]
        }
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/profile/demo_profile_id/marker/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}
required scope
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [marker_id (SNP), ...] for each requested marker. Example:
    rs3784780 i4000396
endpoint example call and result

GET /3/profile/profile_id/marker/marker_id

Requires OAuth requires token Back To Top ↑

For a user's profile, returns a single profile marker. 

curl "https://api.23andme.com/3/profile/demo_profile_id/marker/rs10195681/" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "id": "rs10195681",
    "alternate_ids": [],
    "gene_names": [],
    "accession_id": "NC_000002.11",
    "start": 18673,
    "end": 18674,
    "is_genotyped": true,
    "is_assayed": true,
    "is_no_call": false,
    "variants": [
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "A",
            "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
            "dosage": 0,
            "is_assayed": true,
            "is_no_call": false
        },
        {
            "accession_id": "NC_000002.11",
            "start": 18673,
            "end": 18674,
            "allele": "C",
            "platform_labels": ["ILMN_CUSTOMv4", "ILMN_OMNIEXv3_CUSTOMv3"],
            "dosage": 2,
            "is_assayed": true,
            "is_no_call": false
        }
    ]
}

In the event that there are multiple profile markers for the same set of variants, the other, "alias" marker ids of the requested profile marker will be listed under the alternate_ids attribute of the returned object. For example: 

curl "https://api.23andme.com/3/marker/i5019493/"
# JSON response:
{
    "id": "i5019493",
    "alternate_ids": ['i5035002'],
    ...
}

i5035002 is an alias for the requested profile marker, i5019493.

required scope
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [id, ...] for each requested marker. Example:
    rs3784780 i4000396
Variant Object

A variant, or allele, is a possible variation at a genetic locus or region on a chromosome. The set of variants at a locus may be denoted by a particular marker. Variant data correlates to the GRCh37 human reference genome.

accession_id
string		 the unique id for the accession to which the variant belongs
start
integer		 the chromosomal location of the start of the variant (counting from 0)
end
integer		 the chromosomal location of the end of the variant (counting from 0)
allele
string		 the nucleotide sequence of the variant
platform_labels
list		 labels for the platforms that the variant is on. The following platforms are supported:
  • ILMN_550
  • ILMN_550Qv1_CUSTOMv2
  • ILMN_550v3
  • ILMN_550v3_CUSTOMv1
  • ILMN_CUSTOMv1
  • ILMN_CUSTOMv4
  • ILMN_GSA_CUSTOMv5
  • ILMN_GSA_CUSTOMv5_2
  • ILMN_OMNIEXv3_CUSTOMv3
endpoint example call and result

GET /3/variant/

required:
  • accession_id string
    • or
  • chromosome_id string
    • or
  • gene_name string
parameters for accession_id and chromosome_id:
  • start integer, optional, default 0
  • end integer, optional, min 0, max/default is the last end position of the specified accession (length - 1)
  • platform_label string, optional
    one of:
    • ILMN_550
    • ILMN_550Qv1_CUSTOMv2
    • ILMN_550v3
    • ILMN_550v3_CUSTOMv1
    • ILMN_CUSTOMv1
    • ILMN_CUSTOMv4
    • ILMN_GSA_CUSTOMv5
    • ILMN_GSA_CUSTOMv5_2
    • ILMN_OMNIEXv3_CUSTOMv3
pagination parameters:
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0
Back To Top ↑

Gets a list of variants ordered by their start and end positions. Must use exactly one of accession_id, chromosome_id or gene_name. Optionally, start and end may only be used with accession_id or chromosome_id.

The gene_name parameter will return a list of variants for that gene.

curl "https://api.23andme.com/3/variant/?gene_name=ACTN3"

The accession_id and chromosome_id parameters will return a list of variants on the corresponding chromosome.

curl "https://api.23andme.com/3/variant/?accession_id=NC_012920.1"
curl "https://api.23andme.com/3/variant/?chromosome_id=MT"
# JSON response:
{
    "data": [
        {
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "allele": "C",
            "platform_labels": [
                "ILMN_550Qv1_CUSTOMv2",
                "ILMN_CUSTOMv4",
                "ILMN_OMNIEXv3_CUSTOMv3"
            ]
        },
        {
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "allele": "T",
            "platform_labels": [
                "ILMN_550Qv1_CUSTOMv2",
                "ILMN_CUSTOMv4",
                "ILMN_OMNIEXv3_CUSTOMv3"
            ]
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/variant/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}

The start parameter will load variants with end positions greater than or equal to this value. It must be greater than or equal to 0 and less than the length of the accession. It is 0 by default.

The end parameter will load variants with start positions less than or equal to end. It must be greater than or equal to 0 and less than the length of the specified accession. By default, it is the maximum end position of the specified accession.

Note that variants returned inside the specified start and end range do not have to be entirely contained within that range. Any overlapping variants will be returned.

offset and limit can be used to page through the variants. For example, limit=10 and offset=0 will return items 1-10. Furthermore, limit=10 and offset=10 will return items 11-20. 

curl "https://api.23andme.com/3/variant/?accession_id=NC_000015.9&start=75042285&end=75042485"
# JSON response:
{
    "data": [...],
    "links": {
        "next": "https://api.23andme.com/3/variant/?accession_id=NC_000015.9&start=75042385&end=75042485&limit=100&offset=100"
    }
}

In the above example, the next link contains an auto-incremented offset, which will return the next page of data. Each successive next link can be followed until it is null, in which case all results have been exhausted.

Profile Variant Object

In addition to the reference data provided by the variant object, the profile variant includes genetic data specific to a profile owner's genotype. Profile variant data correlates to the GRCh37 human reference genome.

. . . (same attributes as variant)
dosage
integer		 the occurrence of the allele in the profile owner's genotype (0: no occurrences of the allele, 1: heterozygous, 2: homozygous)
is_assayed
boolean		 true if the profile variant has been assayed
is_no_call
boolean		 true if the assay was performed and there were no results
endpoint example call and result

GET /3/profile/profile_id/variant/

required:
  • accession_id string
    • or
  • chromosome_id string
    • or
  • gene_name string
parameters for accession_id and chromosome_id:
  • start integer, optional, default 0
  • end integer, optional, min 0, max/default is the last end position of the specified accession (length - 1)
  • platform_label string, optional
    one of:
    • ILMN_550
    • ILMN_550Qv1_CUSTOMv2
    • ILMN_550v3
    • ILMN_550v3_CUSTOMv1
    • ILMN_CUSTOMv1
    • ILMN_CUSTOMv4
    • ILMN_GSA_CUSTOMv5
    • ILMN_GSA_CUSTOMv5_2
    • ILMN_OMNIEXv3_CUSTOMv3
pagination parameters:
  • limit integer, optional, default 100, min 1, max 10000
  • offset integer, optional, default 0, min 0
Requires OAuth requires token Back To Top ↑

For the user's profile, gets a list of profile variants ordered by their start and end positions.

Accepts the same request parameters as GET /variant. 

curl "https://api.23andme.com/3/profile/demo_profile_id/variant/?accession_id=NC_012920.1" \
 -H "Authorization: Bearer demo_oauth_token"

# JSON response:
{
    "data": [
        {
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "allele": "C",
            "platform_labels": [
                "ILMN_550Qv1_CUSTOMv2",
                "ILMN_CUSTOMv4",
                "ILMN_OMNIEXv3_CUSTOMv3"
            ],
            "dosage": 0,
            "is_assayed": true,
            "is_no_call": false
        },
        {
            "accession_id": "NC_012920.1",
            "start": 2,
            "end": 3,
            "allele": "T",
            "platform_labels": [
                "ILMN_550Qv1_CUSTOMv2",
                "ILMN_CUSTOMv4",
                "ILMN_OMNIEXv3_CUSTOMv3"
            ],
            "dosage": 1,
            "is_assayed": true,
            "is_no_call": false
        },
        ...
    ],
    "links": {
        "next": "https://api.23andme.com/3/profile/demo_profile_id/variant/?accession_id=NC_012920.1&limit=100&offset=100"
    }
}
required scope
  • genomes - all genetic loci
or
  • accession:<accession_id> - all genetic loci on the specified accession. Example:
    accession:NC_000023.10
or
  • [marker_id (SNP), ...] for each marker associated with the requested variants. Example:
    rs3784780 i4000396

Report Endpoints


Genetic Phenotype Range Interaction (GPRI) Object

A Genetic Phenotype Range Interaction (GPRI) represents an interaction between two phenotypic characteristics. A concrete example is the impact of fast food consumption frequency on a BMI score.

How do genetics come into play? Humans are divided up into discrete groups (called "bins") based on their genetics. How much the variable phenotype (like fast food consumption frequency) impacts the observed phenotype (like BMI score) will depend on which bin a person belongs to.

Each GPRI is associated with a predictor. The predictor will give the 23andMe customer their bin number. Given a list of GPRIs from this endpoint, you can find the details for a given bin number by finding the matching bins object in the list under each GPRI.

A bin with a larger maximum_difference_value means that changing the variable phenotype will have a relatively larger impact on the observed phentoype than a bin with a smaller one, based on a person's genetics.

id
string		 unique string identifying GPRI (e.g. bmi_by_daily_vegetable_servings_and_gbmi)
name
string		 the human-readable name of the GPRI
predictor_id
string		 the unique id associated with the predictor.
variable_phenotype_id
string		 the unique id of the phenotypic characteristic that influences the observed phenotype. (this is the independent variable.)
observed_phenotype_id
string		 the unique id of the phenotypic characteristic that is influenced by the variable phenotype. (this is the dependent variable.)
bins
object

object containing information about the potential difference in weight that could come from varying the behavior, keyed by genetic bin number. Each bin includes:

  • maximum_difference_value - the % by which a person can affect their observed_phenotype characteristic by varying the variable one
  • maximum_difference_explanation - a human-readable text string describing the maximum_difference_value.

The relevant bins for a profile can be looked up in the response + of this endpoint by matching the profile's genetic bin number.
endpoint example call and result

GET /3/genetic_phenotype_range_interaction

parameters:
  • predictor_id string, required
Back To Top ↑

For the supplied predictor_id, lists all GPRI objects associated with the given predictor. 

curl "https://api.23andme.com/3/genetic_phenotype_range_interaction/?predictor_id=linear_regression.gbmi.european_genetics_only_bmi_predictor"
The relevant bins for a profile can be looked up in the response of this + endpoint by matching the profile's bin number. 
# JSON response:
{
  "data": [
    {
      "id": "bmi_by_fast_food_frequency_and_gbmi",
      "name": "Avoiding fast food",
      "predictor_id": "linear_regression.gbmi.european_genetics_only_bmi_predictor",
      "variable_phenotype_id": "phenotypic_concept.fast_food_frequency",
      "observed_phenotype_id": "composed_phenotype.bmi_combined",
      "bins": {
        "1": {
          "maximum_difference_value": "11.3",
          "maximum_difference_explanation": "People who never ate fast food weighed up to 11.3% less than those who ate fast food almost every day or more. "
        },
        "2": {
          "maximum_difference_value": "11.7",
          "maximum_difference_explanation": "People who never ate fast food weighed up to 11.7% less than those who ate fast food almost every day or more. "
        },
        ...
      ]
    },
    {
      "id": "bmi_by_daily_fruit_servings_and_gbmi",
      "name": "Eating fruit",
      "predictor_id": "linear_regression.gbmi.european_genetics_only_bmi_predictor",
      "variable_phenotype_id": "phenotypic_concept.daily_fruit_servings",
      "observed_phenotype_id": "composed_phenotype.bmi_combined",
      "bins": {
        "1": {
          "maximum_difference_value": "5.5",
          "maximum_difference_explanation": "People who ate at least 5 servings of fruit (not including fruit juice) per day weighed up to 5.5% less than those who never ate fruit."
        },
        "2": {
          "maximum_difference_value": "5.7",
          "maximum_difference_explanation": "People who ate at least 5 servings of fruit (not including fruit juice) per day weighed up to 5.7% less than those who never ate fruit."
        },
        ...
      ]
    }
  ],
  "links": {
    "next": null
  }
}