1001 Genomes API

This web services based API provides programmatic access to the 1135 strains data.

Please note that we are still in BETA phase. If you encounter any issues, please contact joffrey.fitz@tuebingen.mpg.de. As well, any suggestions are welcome.

Overview

Currently we provide the following services. More to come.

Usage

This is a free service for the scientific community. We currently have an IP address based rate limit of 2 requests/second.

If you find this API useful, then please acknowledge Joffrey Fitz and Detlef Weigel (weigelworld.org), and 1001genomes.org.

API Reference

GET /api/v1/pseudogenomes/strains/:strains/gids/:gids

Download pseudogenome sequences for the given strains and gene identifiers.

Resource URL

https://tools.1001genomes.org/api/v1/pseudogenomes/strains/:strains/gids/:gids

Parameters

strains
gids

Response format

Plain text FASTA

Examples

https://tools.1001genomes.org/api/v1/pseudogenomes/strains/88/gids/At1G01070.1 https://tools.1001genomes.org/api/v1/pseudogenomes/strains/88,108/gids/At1G01070.1,AT1G01060.2

GET /api/v1/pseudogenomes/strains/:strains/regions/:regions

Download pseudogenome sequences for the given strains and chromosome regions.

Resource URL

https://tools.1001genomes.org/api/v1/pseudogenomes/strains/:strains/regions/:regions

Parameters

strains
regions

Response format

Plain text FASTA

Examples

https://tools.1001genomes.org/api/v1/pseudogenomes/strains/88,108/regions/Chr1:10000..10100

https://tools.1001genomes.org/api/v1/pseudogenomes/strains/88,108/regions/Chr2:100..200,Chr4:220..300

POST /api/v1/pseudogenomes/

If you need to mix gene identifier and chromosome regions, you can specifiy these as POST parameters.

Resource URL

https://tools.1001genomes.org/api/v1/pseudogenomes

Parameters

strains
gids
regions

Response format

Plain text FASTA

Example

$ curl -X POST -d "strains=88,108&gids=AT1G01070.1&regions=Chr1:3631..5899" \
https://tools.1001genomes.org/api/v1/pseudogenomes

GET /api/v1/vcfsubset/strains/:strains/gids/:gids/type/:type/format/:format

Download subsets of variants in VCF/BCF format for given strains and gene identifiers.

Resource URL

https://tools.1001genomes.org/api/v1/vcfsubset/strains/:strains/gids/:gids/type/:type/format/:format

Parameters

strains
gids
type
format

Response format

Plain text VCF, gzipped VCF or BCF as set by the format parameter.

Examples

https://tools.1001genomes.org/api/v1/vcfsubset/strains/9998,9999/gids/AT1G01070.1,AT1G01070.2/type/fullgenome/format/vcf

https://tools.1001genomes.org/api/v1/vcfsubset/strains/9998,9999/gids/AT1G01070.1,AT1G01070.2/type/snpeff/format/bcf

GET /api/v1/vcfsubset/strains/:strains/regions/:regions/type/:type/format/:format

Download subsets of variants in VCF/BCF format for given strains and regions.

Resource URL

https://tools.1001genomes.org/api/v1/vcfsubset/strains/:strains/regions/:regions/type/:type/format/:format

Parameters

strains
regions
type
format

Response format

Plain text VCF, gzipped VCF or BCF according set by the format parameter.

Examples

https://tools.1001genomes.org/api/v1/vcfsubset/strains/9998,9999/regions/Chr1:1000..1010,Chr2:2000..2010/type/fullgenome/format/vcf

https://tools.1001genomes.org/api/v1/vcfsubset/strains/9998,9999/regions/Chr1:1000..1010,Chr2:2000..2010/type/snpeff/format/bcf

POST /api/v1/vcfsubset/

Download subsets of variants in VCF/BCF format for given strains and/or regions.

Resource URL

https://tools.1001genomes.org/api/v1/vcfsubset/

Parameters

strains
regions
gids
type
format

Response format

Plain text VCF, gzipped VCF or BCF according set by the format parameter.

Example

curl -X POST https://tools.1001genomes.org/api/v1/vcfsubset/ \
-d "strains=9998,9999&regions=1:200-220,3:390-400&type=fullgenome&format=vcf"

GET /api/v2/gi2coords/:ann/:gi

Convert gene identifiers to region coordinates.

Resource URL

https://tools.1001genomes.org/api/v2/gi2coords/:ann/:gi

Parameters

ann
gi

Response format

The region string in the format ^Chr:\d+\.\.\d+$ , e.g. Chr1:3000..4000, and the direction (+/-) as JSON string.

Example:

{
    "regions": [{
        "reg_str": "Chr1:38752..40944",
        "dir": "-"
    }, {
        "reg_str": "Chr1:38752..40927",
        "dir": "-"
    }]
}

Example

https://tools.1001genomes.org/api/v2/gi2coords/TAIR10/AT1G01070.1

https://tools.1001genomes.org/api/v2/gi2coords/Araport11/AT1G01070.1,AT1G01070.2

GET /api/v1.1/variants.:format

Get variants for given region or gene identifier, and accession with optional filters.

Resource URL

https://tools.1001genomes.org/api/v1.1/variants.:format

Parameters

format
accs
gid
chr
start
end
pos
type
impact
effect
    3_prime_UTR_truncation
    3_prime_UTR_variant
    5_prime_UTR_premature
    5_prime_UTR_truncation
    5_prime_UTR_variant
    bidirectional_gene_fusion
    coding_sequence_variant
    conserved_intergenic_variant
    conserved_intron_variant
    disruptive_inframe_deletion
    disruptive_inframe_insertion
    downstream_gene_variant
    duplication
    exon_loss_variant
    exon_variant
    feature_ablation
    frameshift_variant
    gene_fusion
    gene_variant
    inframe_deletion
    inframe_insertion
    initiator_codon_variant
    intergenic_region
    intragenic_variant
    intron_variant
    inversion
    miRNA
    missense_variant
    protein_protein_contact
    rare_amino_acid_variant
    rearranged_at_DNA_level
    regulatory_region_variant
    splice_acceptor_variant
    splice_donor_variant
    splice_region_variant
    start_codon_gain_variant
    start_lost
    start_retained
    stop_gained
    stop_lost
    stop_retained_variant
    structural_interaction_variant
    synonymous_variant
    transcript_variant
    upstream_gene_variant

Response format

Array of array with variant info. The fields are: chromosome, position, accession id, reference call, variant call, impacts, and effects.

{
    "data": [
        ["1", "39033", "88", "G", "A", "40", "LOW,MODIFIER", "synonymous_variant,upstream_gene_variant"]
    ]
}

Examples

All accessions

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=all;gid=At1g01070.1

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=all;gid=At1g01070.1;impact=high

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=all;gid=At1g01070.1;effect=splice_acceptor_variant

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=all;gid=At1g01070.1;impact=high;effect=splice_acceptor_variant

Some accessions

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;gid=At1g01070.1

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;gid=At1g01070.1;impact=high

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;gid=At1g01070.1;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;gid=At1g01070.1;impact=high;effect=stop_gained

With chromosome position locus

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000;impact=high

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=11062,6024;chr=1;start=38000;end=41000;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000;impact=high;effect=stop_gained

Only one position

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;pos=40316

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;pos=40316;impact=high

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;pos=40316;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/variants.json?type=snps;accs=1062,6024;chr=1;pos=40316;impact=high;effect=stop_gained

GET /api/v1.1/effects.:format

Get effect details for given region or gene identifier, and accession, with optional filters.

Resource URL

https://tools.1001genomes.org/api/v1.1/effects.:format

Parameters

format
accs
gid
chr
start
end
pos
type
impact
effect

Response format

Array of array with effect info. The fields are: chromosome, position, accession id, type, effect impact, functional class, codon change, amino acid change, amino acid length, gene name, transcript biotype, gene coding, transcript id, and exon rank. 

{
    "data": [
        ["1","39033","88","synonymous_variant","LOW","SILENT","acC/acT","p.Thr274Thr/c.822C>T","318","AT1G01070","protein_coding","CODING","AT1G01070.2","5"]
    ]
}

Examples

All accessions:

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=all;gid=At1g01070.1

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=all;gid=At1g01070.1;impact=high

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=all;gid=At1g01070.1;effect=splice_acceptor_variant

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=all;gid=At1g01070.1;impact=high;effect=splice_acceptor_variant

Some accessions:

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;gid=At1g01070.1

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;gid=At1g01070.1;impact=high

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;gid=At1g01070.1;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;gid=At1g01070.1;impact=high;effect=stop_gained

With ChrPos locus:

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000;impact=high

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=11062,6024;chr=1;start=38000;end=41000;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;start=38000;end=41000;impact=high;effect=stop_gained

Only one position

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;pos=40316

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;pos=40316;impact=high

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;pos=40316;effect=stop_gained

https://tools.1001genomes.org/api/v1.1/effects.json?type=snps;accs=1062,6024;chr=1;pos=40316;impact=high;effect=stop_gained

Error Codes

202: Gene identifiers

If the requested gene identifier was not found, an error with code 202 will be returned as JSON:

{
    "errors": [{
        "code": 202,
        "message": "Gene identifier not found: At1G01070"
    }
}

203: Regions

If a malformed region string was submitted, an error with code 203 will be returned:

{
    "errors": [{
        "code": 203,
        "message": "Invalid region: Chr1:20"
    }]
}

204: Strains

If a requested strain was not found, an error with code 204 will be returned as JSON:

{
    "errors": [{
        "code": 204,
        "message": "Strain not found: Tomato1"
    }]
}

205: Strains

A strain id must be numeric, otherwise an error with code 205 will be returned as JSON:

{
    "errors": [{
        "code": 205,
        "message": "Invalid strain id: 9999a"
    }]
}

206: VCF Format

If a not supported format is requested, ae error with code 206 will be returned. Currently supported formats are vcf, bcf and vcf.gz.

{
    "errors": [{
        "code": 206,
        "message": "Format 'vf' not supported"
    }]
}

207: VCF Data Source

If an other data type as fullgenome or snpeff is requested, an error with code 207 will be returned:

{
    "errors": [{
        "code": 207,
        "message": "Type 'foo' not supported"
    }]
}

Rate limits

At this time, users can make 2 requests/queries per second.

Version 1.0 — © 2016-2021 Max Planck Institute for Developmental Biology — Contact: joffrey.fitz@tuebingen.mpg.de