EnteroBase API Endpoint Reference¶
The API can be explored using the [interactive documentation](https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui “external link”). The query methods currently in the API are:
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Alleles
The alleles
query method shows sequences for loci, derived from an assembly.
An example of this type of query to try in the interactive documentation which is also on [the page about downloading schemes](api_download_schemes) has “database” set to “senterica”, “scheme” set to “MLST_Achtman”, “reldate” set to “20”, “locus” set to “aroC” and “limit” set to “50”. This will fetch new allele sequences for aroC in the 7 gene MLST scheme for Salmonella from the last 20 days. The corresponds to an HTTP request to the URL:
https://enterobase.warwick.ac.uk/api/v2.0/senterica/MLST_Achtman/alleles?reldate=20&locus=aroC&limit=50
The result is:
{
"alleles": [
{
"allele_barcode": "SAL_AP0358AA_AL",
"allele_id": "716",
"locus": "aroC",
"seq": "GTGTTCCGTCCGGGGCACGCGGATTACACCTACGAACAAAAATACGGCCTGCGCGACTATCGCGGCGGCGGGCGTTCATCCGCCCGTGAAACCGCCATGCGCGTCGCGGCAGGCGCTATCGCCAAAAAATATCTGGCGCAGAAATTCGGCGTGGTGATTCGCGGCTGCCTGACCCAGATGGGTGATATTCCGCTGGAAATCAAAGACTGGGATCAGGTAGAGCAAAACCCGTTCTTCTGCCCGGACCCGGATAAAATCGAGGCGCTGGATGAGCTGATGCGCGCTCTGAAAAAAGAGGGCGATTCCATCGGCGCGAAAGTCACCGTGGTGGCCGACAGCGTGCCCGCCGGGCTTGGCGAGCCGGTATTTGACCGCCTGGACGCCGATATCGCCCACGCGCTGATGAGCATTAACGCCGTGAAGGGCGTGGAAATCGGCGACGGTTTCGGCGTGGTGCAACTGCGCGGCAGCCAGAACCGCGACGAAATCACCACTGCCGGT"
}
],
"links": {
"paging": {},
"records": 1,
"total_records": 1
}
}
Note that as discussed in [the notes about downloading schemes](api_download_schemes) it is inadvisable to download the allele sequences in their entirety using the above method, rather to download a tarball with the daily dump of all data and update with new information at regular intervals using queries like the one above as is described on [that page](api_download_schemes).
The assemblies query method¶
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Assemblies
The assemblies
query method shows metadata for genome assemblies including N50, coverage, size, and links
to FASTA contigs.
An example of this type of query to try in the interactive documentation has “database” set to “senterica”, “orderby” set to “barcode”, “limit” set to “2”, reldate set to “10”, “assembly_status” set to “Assembled” and “sortorder” set to “asc” and corresponds to an HTTP request to the URL
which (at the time of the query) obtained the result
{
"Assemblies": [
{
"assembly_barcode": "SAL_IA5204AA_AS",
"assembly_status": "Assembled",
"coverage": null,
"download_fasta_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_IA5204AA_AS&database=senterica",
"download_fastq_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_IA5204AA_AS&database=senterica&file_format=fastq",
"id": 85204,
"lastmodified": "2017-05-01T22:02:56.892765+00:00",
"n50": 406329,
"top_species": "Salmonella enterica;96.66%",
"version": 1
},
{
"assembly_barcode": "SAL_KA9491AA_AS",
"assembly_status": "Assembled",
"coverage": 58,
"download_fasta_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_KA9491AA_AS&database=senterica",
"download_fastq_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_KA9491AA_AS&database=senterica&file_format=fastq",
"id": 109491,
"lastmodified": "2017-04-30T17:32:38.119705+00:00",
"n50": 276765,
"top_species": "Salmonella enterica;93.44%",
"version": 1
}
],
"links": {
"paging": {
"next": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/assemblies?orderby=barcode&limit=2&reldate=10&offset=2&assembly_status=Assembled&sortorder=asc"
},
"records": 2,
"total_records": 412
}
}
[The page about downloading assemblies](api_download_assemblies) has an example
where metadata is obtained for an assembly via the [straindata
](api_straindata) endpoint which
may be more convenient for particular applications.
As noted on that page, it works well to fetch assemblies’ metadata via an assemblies
query
method if you already have assembly barcodes. For example, try an assemblies
query in the
interactive documentation for the database senterica with “barcode” set to “SAL_IA5204AA_AS”
which corresponds to a request to the URL
https://enterobase.warwick.ac.uk/api/v2.0/senterica/assemblies?barcode=SAL_IA5204AA_AS
and obtains the result
{
"Assemblies": [
{
"assembly_barcode": "SAL_IA5204AA_AS",
"assembly_status": "Assembled",
"coverage": null,
"download_fasta_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_IA5204AA_AS&database=senterica",
"download_fastq_link": "https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_IA5204AA_AS&database=senterica&file_format=fastq",
"id": 85204,
"lastmodified": "2017-05-01T22:02:56.892765+00:00",
"n50": 406329,
"top_species": "Salmonella enterica;96.66%",
"version": 1
}
],
"links": {
"paging": {},
"records": 1,
"total_records": 1
}
}
The info query method¶
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Info
The info
query method shows a “site map” of API URLs.
For example, an info
query with the parameter “name” set to “senterica” (for that database).
A request is made to the URL
returning the result
[
{
"description": "Salmonella",
"links": {
"assemblies": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/assemblies",
"current": "https://enterobase.warwick.ac.uk/api/v2.0",
"schemes": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/schemes",
"straindata": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata",
"strains": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/strains",
"sts": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/rMLST/sts",
"traces": "https://enterobase.warwick.ac.uk/api/v2.0/senterica/traces"
},
"name": "senterica",
"prefix": "SAL",
"tables": "{'schemes': 'SC', 'snps': 'SN', 'alleles': 'AL', 'assemblies': 'AS', 'loci': 'LO', 'taxondef': 'TA', 'strains': 'SS', 'datadefs': 'DE', 'sts': 'ST', 'traces': 'TR', 'archive': 'AR', 'refsets': 'RE'}"
}
]
providing direct links to the various endpoints in the given database.
The loci query method¶
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Loci
The loci
query method shows metadata for loci for genotyping schemes. This includes links
allowing download of the allele sequences for the loci (in gzipped FASTA files).
An example of this type of query to try in the interactive documentation which is also on [the page about downloading schemes](api_download_schemes) has “database” set to “senterica”, “scheme” set to “MLST_Achtman” (as a parameter and in the path) and “limit” set to “50”. This corresponds to an HTTP request to the URL:
This gives the result:
{
"links": {
"paging": {},
"records": 7,
"total_records": 7
},
"loci": [
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=aroC&scheme=UoW&species=Salmonella",
"locus": "aroC",
"locus_barcode": "SAL_AA0001AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=dnaN&scheme=UoW&species=Salmonella",
"locus": "dnaN",
"locus_barcode": "SAL_AA0002AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=hemD&scheme=UoW&species=Salmonella",
"locus": "hemD",
"locus_barcode": "SAL_AA0003AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=hisD&scheme=UoW&species=Salmonella",
"locus": "hisD",
"locus_barcode": "SAL_AA0004AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=purE&scheme=UoW&species=Salmonella",
"locus": "purE",
"locus_barcode": "SAL_AA0005AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=sucA&scheme=UoW&species=Salmonella",
"locus": "sucA",
"locus_barcode": "SAL_AA0006AA_LO",
"scheme": "UoW"
},
{
"database": "Salmonella",
"download_alleles_link": "https://enterobase.warwick.ac.uk/download_data?allele=thrA&scheme=UoW&species=Salmonella",
"locus": "thrA",
"locus_barcode": "SAL_AA0007AA_LO",
"scheme": "UoW"
}
]
}
The login query method¶
Refer to the interactive documentation at https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Login (although you may want to avoid trying this interactively if you do not intend to change your API token at this time).
The login
query method is not really a pure query method since it also causes the API token to be refreshed
(changing the API token as a result and avoiding expiration of the API token). The result of the query includes
the new API token.
This is discussed on the page about [automatically renewing the API token](api_renew_login).
The lookup query method¶
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Lookup
The lookup
query method allows lookup of any EnteroBase barcode. (Barcodes for any type of data can be looked
up with lookup
. It is like a “Swiss army knife” query method and usually a query method specific to a
particular type of data will be more suitable e.g. the assemblies
query method for queries relating to
assemblies.)
An example of this type of query to try in the interactive documentation is to set “barcode” to “SAL_AA0001AA_LO”
which is equivalent to an HTTP request to the URL:
https://enterobase.warwick.ac.uk/api/v2.0/lookup?barcode=SAL_AA0001AA_LO
Another example for looking up a scheme barcode sets the barcode to “SAL_AA0010AA_SC” (for the cgMLST version 4 scheme in Salmonella):
https://enterobase.warwick.ac.uk/api/v2.0/lookup?barcode=SAL_AA0010AA_SC
giving the result
- {
“records”: 1, “results”: [
- {
“accepted”: 1, “barcode”: “SAL_AA0010AA_SC”, “create_time”: “2016-01-27 17:39:55.279130”, “detail”: “”, “index_id”: 10, “info”: {
“ext_db”: null, “ext_site”: null, “incremental”: false, “max_flanking”: 30, “merging_error”: 0.08, “merging_prop”: 0.5, “min_flanking”: 9, “min_frag_len”: 50, “min_frag_prop”: 0.3, “min_frag_sum”: 0.45, “min_iden”: 0.75, “min_prop”: 1, “position”: false, “ref_iden”: 0.96, “value_type”: “text”}, “lastmodified”: “2016-02-11 18:20:43.713484”, “lastmodified_by”: “enterotool”, “mode”: “MLST”, “scheme”: “cgMLSTv4”, “table_alias”: {
“STs”: “STs”, “alleles”: “alleles”, “loci”: “loci”, “nomenclature_records”: “nomenclature_records”, “refsets”: “refsets”, “schemes”: “schemes”, “taxa”: “taxa”}, “taxon_index”: 1, “value_alias”: {
“ST_id”: “ST_id”, “ST_index”: “ST_index”, “STs”: “STs”, “Strain_barcode”: “Strain_barcode”, “accepted”: “accepted”, “allele_id”: “allele_id”, “allele_index”: “allele_index”, “allele_indices”: “allele_indices”, “allele_name”: “allele_name”, “alleles”: “alleles”, “contig_name”: “contig_name”, “detail”: “detail”, “fullname”: “fullname”, “info”: “info”, “loci”: “loci”, “locus”: “locus”, “locus_index”: “locus_index”, “mode”: “mode”, “nomenclature_records”: “nomenclature_records”, “prefix”: “prefix”, “ref_allele”: “ref_allele”, “reference”: “reference”, “refname”: “refname”, “refsets”: “refsets”, “scheme”: “scheme”, “schemes”: “schemes”, “seq”: “seq”, “start”: “start”, “stop”: “stop”, “taxa”: “taxa”, “taxon”: “taxon”}, “version”: 2
}
]
}
Another example of this type of query to try in the interactive documentation which is also on [the page about the API structure](api_structure) (which also has a discussion of barcodes) is to have “barcode” equal to “SAL_AA0019AA_ST” which is equivalent to an HTTP request to the URL:
https://enterobase.warwick.ac.uk/api/v2.0/lookup?barcode=SAL_AA0019AA_ST
which gives the result (concerning Sequence Type 19, Salmonella Typhimurium)
{
"records": 1,
"results": [
{
"ST_id": 19,
"accepted": 1,
"alleles": [
{
"accepted": 1,
"allele_id": 10,
"allele_name": null,
"locus": "aroC"
},
{
"accepted": 1,
"allele_id": 7,
"allele_name": null,
"locus": "dnaN"
},
{
"accepted": 1,
"allele_id": 12,
"allele_name": null,
"locus": "hemD"
},
{
"accepted": 1,
"allele_id": 9,
"allele_name": null,
"locus": "hisD"
},
{
"accepted": 1,
"allele_id": 5,
"allele_name": null,
"locus": "purE"
},
{
"accepted": 1,
"allele_id": 9,
"allele_name": null,
"locus": "sucA"
},
{
"accepted": 1,
"allele_id": 2,
"allele_name": null,
"locus": "thrA"
}
],
"barcode": "SAL_AA0019AA_ST",
"create_time": "2015-11-24 19:59:36.295460",
"index_id": 19,
"info": {
"lineage": "",
"predict": {
"serotype": [
[
"Typhimurium",
7372
],
[
"Typhimurium Var. 5-",
440
],
[
"Typhimurium Var. O:5-",
208
]
},
"st_complex": "1",
"subspecies": ""
},
"lastmodified": "2017-02-19 01:44:21.503891",
"lastmodified_by": "admin",
"reference": {
"lab_contact": "DVI",
"refstrain": "9924828",
"source": "mlst.warwick.ac.uk"
},
"scheme": "UoW",
"scheme_index": 1,
"version": 4885
}
]
}
Looking up an allele barcode with:
http://hercules.warwick.ac.uk/api/v2.0/lookup?barcode=SAL_AP0358AA_AL
obtains the result
{
"records": 1,
"results": [
{
"_combo_tag": "1_716",
"accepted": 1,
"allele_id": 716,
"allele_name": null,
"barcode": "SAL_AP0358AA_AL",
"create_time": "2017-04-14 06:58:05.463744",
"index_id": 3900358,
"lastmodified": "2017-04-14 06:58:05.463744",
"lastmodified_by": "admin",
"locus": "aroC",
"locus_index": 1,
"reference": {
"refstrain": "SAL_FA3594AA_AS",
"source": "mlst.warwick.ac.uk"
},
"scheme": "UoW",
"seq": "GTGTTCCGTCCGGGGCACGCGGATTACACCTACGAACAAAAATACGGCCTGCGCGACTATCGCGGCGGCGGGCGTTCATCCGCCCGTGAAACCGCCATGCGCGTCGCGGCAGGCGCTATCGCCAAAAAATATCTGGCGCAGAAATTCGGCGTGGTGATTCGCGGCTGCCTGACCCAGATGGGTGATATTCCGCTGGAAATCAAAGACTGGGATCAGGTAGAGCAAAACCCGTTCTTCTGCCCGGACCCGGATAAAATCGAGGCGCTGGATGAGCTGATGCGCGCTCTGAAAAAAGAGGGCGATTCCATCGGCGCGAAAGTCACCGTGGTGGCCGACAGCGTGCCCGCCGGGCTTGGCGAGCCGGTATTTGACCGCCTGGACGCCGATATCGCCCACGCGCTGATGAGCATTAACGCCGTGAAGGGCGTGGAAATCGGCGACGGTTTCGGCGTGGTGCAACTGCGCGGCAGCCAGAACCGCGACGAAATCACCACTGCCGGT",
"version": 1
}
]
}
The schemes query method¶
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Schemes
The schemes
query method shows genotyping schemes and pipelines derived from assemblies.
A simple schemes
query will list each scheme in the given EnteroBase database together with associated
metadata. This can be tried in the interactive documentation by simply entering the name of the database
and otherwise using default values of the parameters. This corresponds to an HTTP request to the URL (and is similar to the query in step 1 on [the page about downloading schemes using the API](api_download_schemes “wikilink”)):
https://enterobase.warwick.ac.uk/api/v2.0/senterica/schemes?limit=50&orderby=barcode&sortorder=asc
This gives the result
{
"Schemes": [
{
"created": "2015-11-25T15:39:04.169278+00:00",
"download_sts_link": null,
"label": "Assembly stats",
"lastmodified": "2015-11-27T12:15:31.053974+00:00",
"scheme_barcode": "",
"scheme_name": "assembly_stats",
"version": 1
},
{
"created": "2015-08-26T15:04:34.033635+00:00",
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=UoW&species=Salmonella",
"label": "Achtman 7 Gene",
"lastmodified": "2015-12-07T17:50:17.186416+00:00",
"scheme_barcode": "SAL_AA0001AA_SC",
"scheme_name": "MLST_Achtman",
"version": 1
},
{
"created": "2015-11-25T15:39:05.748726+00:00",
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=rMLST&species=Salmonella",
"label": "rMLST",
"lastmodified": "2015-12-07T17:50:17.186416+00:00",
"scheme_barcode": "SAL_AA0002AA_SC",
"scheme_name": "rMLST",
"version": 1
},
{
"created": "2015-12-30T15:39:05.748726+00:00",
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=cgMLSTv4&species=Salmonella",
"label": "cgMLST(3020) Beta",
"lastmodified": "2015-12-30T15:39:05.748726+00:00",
"scheme_barcode": "SAL_AA0010AA_SC",
"scheme_name": "cgMLST",
"version": 4
},
{
"created": null,
"download_sts_link": null,
"label": "Repeat Finder",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "ref_masker",
"version": null
},
{
"created": null,
"download_sts_link": null,
"label": "Serotype Prediction (SISTR)",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "SeroPred",
"version": null
},
{
"created": "2015-12-30T15:39:05.748726+00:00",
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=CRISPR&species=Salmonella",
"label": "CRISPR",
"lastmodified": "2015-12-30T15:39:05.748726+00:00",
"scheme_barcode": null,
"scheme_name": "CRISPR",
"version": 1
},
{
"created": null,
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=wgMLSTv1&species=SALwgMLST",
"label": "wgMLST",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "wgMLST",
"version": null
},
{
"created": "2015-12-30T15:39:05.748726+00:00",
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=CRISPR&species=Salmonella",
"label": "CRISPOL",
"lastmodified": "2015-12-30T15:39:05.748726+00:00",
"scheme_barcode": null,
"scheme_name": "CRISPOL",
"version": 1
},
{
"created": null,
"download_sts_link": "https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=cgMLSTv1&species=SALwgMLST",
"label": "cgMLST V2",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "cgMLST_v2",
"version": null
},
{
"created": null,
"download_sts_link": null,
"label": "Annotation",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "prokka_annotation",
"version": null
},
{
"created": null,
"download_sts_link": null,
"label": "SNP Calls",
"lastmodified": null,
"scheme_barcode": null,
"scheme_name": "snp_calls",
"version": null
}
],
"links": {
"paging": {},
"records": 12,
"total_records": 12
}
}
Also, you can use “only_fields” set to “download_sts_link” in order to just fetch the download link, corresponding to an HTTP request to the URL:
https://enterobase.warwick.ac.uk/api/v2.0/senterica/schemes?limit=50&orderby=barcode&sortorder=asc&only_fields=download_sts_link
which gives the result
- {
- “Schemes”: [
- {
- “download_sts_link”: null
}, {
“download_sts_link”: “https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=UoW&species=Salmonella”}, {
}, {
}, {
“download_sts_link”: null}, {
“download_sts_link”: null}, {
}, {
}, {
}, {
}, {
“download_sts_link”: null}, {
“download_sts_link”: null}
], “links”: {
“paging”: {}, “records”: 12, “total_records”: 12}
}
Another example of this type of query to try in the interactive documentation (and which is representative of a single iteration of the loop in step 2 on [the page about downloading schemes](api_download_schemes “wikilink”)) queries the database “senterica” and has “scheme_name” set to “MLST_Achtman”, “limit” set to “50” and “only_fields” set to “download_sts_link” and is request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/schemes?limit=50&orderby=barcode&sortorder=asc&only_fields=download_sts_link&scheme_name=MLST_Achtman
`
This gets the result below, with the request for the MLST_Achtman scheme only:
``` {
- “Schemes”: [
- {
- “created”: “2015-08-26T15:04:34.033635+00:00”, “download_sts_link”: “https://enterobase.warwick.ac.uk/download_data?allele=profiles&scheme=UoW&species=Salmonella”, “label”: “Achtman 7 Gene”, “lastmodified”: “2015-12-07T17:50:17.186416+00:00”, “scheme_barcode”: “SAL_AA0001AA_SC”, “scheme_name”: “MLST_Achtman”, “version”: 1
}
], “links”: {
“paging”: {}, “records”: 1, “total_records”: 1}
}¶
#Searching strain data - the straindata query method See also the interactive documentation at https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Straindata
The straindata
query method combines data from strains, assemblies and STs to give a single access for most data. (If only one of these types of data is desired, then it may be better to use a different query method in the API - for possible alternatives see [the diagram on the page about the API structure](api_structure#markdown-header-understanding-the-enterobase-api-structure).)
An example to try in the Swagger UI for straindata
is to enter “Agona” for serotype, “Assembled” for assembly_status and “senterica” for database (and otherwise leave the defaults in the Swagger UI). This corresponds to an HTTP GET request (using an API key) with the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?serotype=Agona&sortorder=asc&assembly_status=Assembled&limit=50
`
The results are a bit long to show in full in this documentation - a similar query with limit set to the smaller value 3 gives the result: ``` {
- “links”: {
- “paging”: {
- “next”: “https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?limit=3&sortorder=asc&offset=3&serotype=Agona&assembly_status=Assembled”
}, “records”: 1, “total_records”: 2974
}, “straindata”: {
- “SAL_EA9564AA”: {
“assembly_barcode”: “SAL_KA3160AA_AS”, “assembly_status”: “Assembled”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 2015, “comment”: null, “continent”: “North America”, “country”: “United States”, “county”: null, “created”: “2016-02-06T19:55:02.784586+00:00”, “download_fasta_link”: “https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_KA3160AA_AS&database=senterica”, “email”: null, “lab_contact”: “United States Department of Agriculture, Food Safety and Inspection Service”, “lastmodified”: “2016-09-07T16:20:58.720874+00:00”, “latitude”: null, “longitude”: null, “n50”: 234392, “orderby”: “barcode”, “postcode”: null, “region”: “Iowa”, “secondary_sample_accession”: “SRS1278094”, “serotype”: “Agona”, “source_details”: “Animal-Swine-Sow”, “source_niche”: “Livestock”, “source_type”: “Air”, “strain_barcode”: “SAL_EA9564AA”, “strain_name”: “FSIS1605678”, “sts”: [
- {
- “scheme_name”: “cgMLST”, “st_barcode”: “SAL_AB4818AA_ST”, “st_id”: 71634, “timestamp”: “2016-10-13 18:49:32.791374”, “version”: “3.1”
}, {
“predicted_serotype”: “Agona”, “scheme_name”: “rMLST”, “species”: “Salmonella enterica”, “st_barcode”: “SAL_RA4278AA_ST”, “st_complex”: “54”, “st_id”: 33136, “timestamp”: “2017-03-16 22:50:26.193849”, “version”: “3.0”}, {
“predicted_serotype”: “Agona”, “scheme_name”: “MLST_Achtman”, “st_barcode”: “SAL_AA0013AA_ST”, “st_complex”: “54”, “st_id”: 13, “timestamp”: “2017-04-26 03:08:13.847632”, “version”: “3.0”}
], “top_species”: “Salmonella enterica;96.48%”, “uberstrain”: “SAL_EA9564AA”, “version”: 1
}
}
}¶
In order to reduce the amount of content downloaded and speed up the query, “only_fields” may be used, for example, setting “only_fields” to “strain_name,download_fasta_link” (and adding this to the above example). This corresponds to an HTTP request with the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?serotype=Agona&only_fields=strain_name%2Cdownload_fasta_link&sortorder=asc&assembly_status=Assembled&limit=50
`
The result with limit set to 3 is: ``` {
- “links”: {
- “paging”: {
- “next”: “https://enterobase.warwick.ac.uk/api/v2.0/senterica/straindata?only_fields=strain_name%2Cdownload_fasta_link&limit=3&sortorder=asc&offset=3&serotype=Agona&assembly_status=Assembled”
}, “records”: 1, “total_records”: 2974
}, “straindata”: {
- “SAL_EA9564AA”: {
“assembly_barcode”: “SAL_KA3160AA_AS”, “download_fasta_link”: “https://enterobase.warwick.ac.uk/upload/download?assembly_barcode=SAL_KA3160AA_AS&database=senterica”, “strain_barcode”: “SAL_EA9564AA”, “strain_name”: “FSIS1605678”, “sts”: [
- {
- “scheme_name”: “cgMLST”, “st_barcode”: “SAL_AB4818AA_ST”, “st_id”: 71634, “timestamp”: “2016-10-13 18:49:32.791374”, “version”: “3.1”
}, {
“predicted_serotype”: “Agona”, “scheme_name”: “rMLST”, “species”: “Salmonella enterica”, “st_barcode”: “SAL_RA4278AA_ST”, “st_complex”: “54”, “st_id”: 33136, “timestamp”: “2017-03-16 22:50:26.193849”, “version”: “3.0”}, {
“predicted_serotype”: “Agona”, “scheme_name”: “MLST_Achtman”, “st_barcode”: “SAL_AA0013AA_ST”, “st_complex”: “54”, “st_id”: 13, “timestamp”: “2017-04-26 03:08:13.847632”, “version”: “3.0”}
]
}
}
}¶
# The strains query method #
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Strains
The strains
query method shows the strain metadata such as host, geography and lab contacts.
An example of this type of query to try in the interactive documentation has database set to “senterica” and “strain name” set to “FSIS1605678” which corresponds to a request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/strains?strain_name=FSIS1605678
`
giving the results
``` {
- “Strains”: [
- {
- “antigenic_formulas”: null, “assembly_barcode”: “SAL_KA3160AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 2015, “comment”: null, “continent”: “North America”, “country”: “United States”, “county”: null, “created”: “2016-02-06T19:00:03.611332+00:00”, “lab_contact”: “United States Department of Agriculture, Food Safety and Inspection Service”, “lastmodified”: “2016-02-06T19:55:02.798303+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: “Iowa”, “secondary_sample_accession”: “SRS1278094”, “serotype”: “Agona”, “source_details”: “Animal-Swine-Sow”, “source_niche”: “Livestock”, “source_type”: “Air”, “strain_barcode”: “SAL_EA9564AA”, “strain_name”: “FSIS1605678”, “uberstrain”: “SAL_EA9564AA”, “version”: 1
}
], “links”: {
“paging”: {}, “records”: 1, “total_records”: 1}
}¶
Another example of this type of query to try in the interactive documentation has database set to “senterica”, “serotype” set to “Agona” and “limit” to “5” which corresponds to a request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/strains?serotype=Agona&limit=5
`
giving the results
``` {
- “Strains”: [
- {
- “antigenic_formulas”: “4,12:g,s,t:z27”, “assembly_barcode”: “SAL_AA0605AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 1974, “comment”: null, “continent”: “Europe”, “country”: “United Kingdom”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “F. Boyd”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “Water”, “source_niche”: null, “source_type”: “Environment”, “strain_barcode”: “SAL_AA0605AA”, “strain_name”: “SARA61 (Fidelma Boyd)”, “uberstrain”: “SAL_AA0605AA”, “version”: 1
}, {
“antigenic_formulas”: “1,4,[5],12:f,g,s:[1,2]”, “assembly_barcode”: “SAL_AA0606AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: null, “comment”: null, “continent”: “Europe”, “country”: “Denmark”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “SSI”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “”, “source_niche”: null, “source_type”: “Human”, “strain_barcode”: “SAL_AA0606AA”, “strain_name”: “993112K”, “uberstrain”: “SAL_AA0606AA”, “version”: 1}, {
“antigenic_formulas”: “4,12:f,g,s:-“, “assembly_barcode”: “SAL_AA0607AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 1971, “comment”: null, “continent”: “Europe”, “country”: “France”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “F.X.Weill, Institut Pasteur”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “”, “source_niche”: null, “source_type”: “Human”, “strain_barcode”: “SAL_AA0607AA”, “strain_name”: “2-71”, “uberstrain”: “SAL_AA0607AA”, “version”: 1}, {
“antigenic_formulas”: “1,4,[5],12:f,g,s:[1,2]”, “assembly_barcode”: “SAL_AA0608AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: null, “comment”: null, “continent”: “Europe”, “country”: “Denmark”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “SSI”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “”, “source_niche”: null, “source_type”: “Human”, “strain_barcode”: “SAL_AA0608AA”, “strain_name”: “993212K”, “uberstrain”: “SAL_AA0608AA”, “version”: 1}, {
“antigenic_formulas”: “4,12:f,g,s:-“, “assembly_barcode”: “SAL_AA0609AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 1969, “comment”: null, “continent”: “Europe”, “country”: “France”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “F.X.Weill, Institut Pasteur”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “Liver”, “source_niche”: null, “source_type”: “Swine”, “strain_barcode”: “SAL_AA0609AA”, “strain_name”: “5-69”, “uberstrain”: “SAL_AA0609AA”, “version”: 1}
], “links”: {
- “paging”: {
- “next”: “https://enterobase.warwick.ac.uk/api/v2.0/senterica/strains?orderby=barcode&limit=5&sortorder=asc&offset=5&serotype=Agona”
}, “records”: 5, “total_records”: 780
}
}¶
# The strainsversion query method #
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Strainsversion
The strainsversion
query method shows previous versions of the strain metadata such as host, geography
and lab contacts.
An example of this type of query to try in the interactive documentation has database set to “senterica” and “strain name” set to “FSIS1605678” which corresponds to a request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/strainsversion?strain_name=FSIS1605678
`
giving the result with no old versions
``` {
“StrainsArchive”: [], “links”: {
“paging”: {}, “records”: 0, “total_records”: 0}
}¶
Another example of this type of query to try in the interactive documentation has database set to “senterica” and “strain name” set to “RM_172” which corresponds to a request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/strainsversion?strain_name=RM_172
`
giving the results with one old version
``` {
- “StrainsArchive”: [
- {
- “antigenic_formulas”: “”, “assembly_barcode”: “SAL_AA0630AA”, “city”: null, “collection_date”: null, “collection_month”: null, “collection_time”: null, “collection_year”: 2006, “comment”: null, “continent”: “North America”, “country”: “USA”, “county”: null, “created”: “2015-08-26T15:04:33.345763+00:00”, “lab_contact”: “R. Meinersmann (USDA)”, “lastmodified”: “2015-08-26T15:04:33.345796+00:00”, “latitude”: null, “longitude”: null, “postcode”: null, “region”: null, “secondary_sample_accession”: “NA”, “serotype”: “Agona”, “source_details”: “River”, “source_niche”: null, “source_type”: “Environment”, “strain_barcode”: “SAL_AA0630AA”, “strain_name”: “RM_172”, “uberstrain”: “SAL_AA0630AA”, “version”: 1
}
], “links”: {
“paging”: {}, “records”: 1, “total_records”: 1}
}¶
And the request for “strain name” set to “Ragna”, also using “only_fields”:
`
http://hercules.warwick.ac.uk/api/v2.0/senterica/strainsversion?only_fields=city&only_fields=collection_year&only_fields=country&only_fields=lastmodified&only_fields=serotype&only_fields=source_details&only_fields=source_type&only_fields=strain_barcode&only_fields=strain_name&only_fields=version&strain_name=Ragna
`
gives 9 old versions:
``` {
- “StrainsArchive”: [
- {
- “city”: “Trondheim”, “collection_year”: 1800, “country”: “Norway”, “lastmodified”: “2016-10-28T13:03:01.679343+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 1
}, {
“city”: “Trondheim”, “collection_year”: null, “country”: “Norway”, “lastmodified”: “2016-10-28T15:49:55.690802+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 2}, {
“city”: “Trondheim”, “collection_year”: null, “country”: “Norway”, “lastmodified”: “2016-10-28T15:50:15.275379+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 3}, {
“city”: “Trondheim”, “collection_year”: null, “country”: “Norway”, “lastmodified”: “2016-10-28T16:21:11.895341+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 4}, {
“city”: “Trondheim”, “collection_year”: null, “country”: “Norway”, “lastmodified”: “2016-11-02T16:23:51.261721+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 5}, {
“city”: “Trondheim”, “collection_year”: 1200, “country”: “Norway”, “lastmodified”: “2016-11-02T18:50:51.950894+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 6}, {
“city”: “Trondheim”, “collection_year”: 1200, “country”: “Norway”, “lastmodified”: “2016-12-01T11:56:01.862835+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth and long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 7}, {
“city”: “Trondheim”, “collection_year”: 1200, “country”: “Denmark”, “lastmodified”: “2017-01-09T12:54:40.712442+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth, long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 8}, {
“city”: “Trondheim”, “collection_year”: 1200, “country”: “Norway”, “lastmodified”: “2017-01-09T12:55:14.647874+00:00”, “serotype”: “Paratyphi C”, “source_details”: “Teeth, long bone”, “source_type”: “Human”, “strain_barcode”: “SAL_HA1701AA”, “strain_name”: “Ragna”, “version”: 9}
], “links”: {
“paging”: {}, “records”: 9, “total_records”: 9}
}¶
#Searching ST data - the sts query method Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Sts
The sts
query method shows Sequence Types (STs) and IDs for pipeline/ genotype data.
An example of this type of query to try in the interactive documentation which is also
on [the page about downloading schemes](api_download_schemes)
has “database” set to “senterica”, “scheme” (in the path and as a parameter) set to “MLST_Achtman”, “show_alleles” set to “false” and “reldate” set to “20”. This fetches the new STs
in the 7 gene MLST scheme from the last 20 days. (Note that you may obtain different results than
in this documentation due to the query being conducted at a different time resulting the query fetching
results for a different time interval.) This corresponds
to an HTTP request (using the API key) with the URL:
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/MLST_Achtman/sts?scheme=MLST_Achtman&show_alleles=false&limit=5&reldate=20
`
The results from this query (at the time of writing this documentation) are: ``` {
- “STs”: [
- {
“ST_id”: “3856”, “barcode_link”: “https://enterobase.warwick.ac.uk/api/v1.0/lookup?barcode=SAL_HB2013AA_ST”, “create_time”: “2017-04-12 15:36:09.782739”, “info”: {
“lineage”: “”, “st_complex”: “224”, “subspecies”: “”}, “reference”: {
“lab_contact”: “public”, “refstrain”: “SAL_RA9042AA_AS”, “source”: “mlst.warwick.ac.uk”}, “scheme”: “UoW”, “st_barcode”: “SAL_HB2013AA_ST”
}, {
“ST_id”: “3857”, “barcode_link”: “https://enterobase.warwick.ac.uk/api/v1.0/lookup?barcode=SAL_HB2022AA_ST”, “create_time”: “2017-04-13 07:38:58.579619”, “info”: null, “reference”: {
“lab_contact”: “public”, “refstrain”: “SAL_RA9134AA_AS”, “source”: “mlst.warwick.ac.uk”}, “scheme”: “UoW”, “st_barcode”: “SAL_HB2022AA_ST”
}, {
“ST_id”: “3858”, “barcode_link”: “https://enterobase.warwick.ac.uk/api/v1.0/lookup?barcode=SAL_HB2024AA_ST”, “create_time”: “2017-04-13 08:22:20.405268”, “info”: null, “reference”: {
“lab_contact”: “public”, “refstrain”: “SAL_RA9183AA_AS”, “source”: “mlst.warwick.ac.uk”}, “scheme”: “UoW”, “st_barcode”: “SAL_HB2024AA_ST”
}, {
“ST_id”: “3859”, “barcode_link”: “https://enterobase.warwick.ac.uk/api/v1.0/lookup?barcode=SAL_HB2026AA_ST”, “create_time”: “2017-04-13 09:59:28.391416”, “info”: null, “reference”: {
“lab_contact”: “public”, “refstrain”: “SAL_RA9211AA_AS”, “source”: “mlst.warwick.ac.uk”}, “scheme”: “UoW”, “st_barcode”: “SAL_HB2026AA_ST”
}, {
“ST_id”: “3860”, “barcode_link”: “https://enterobase.warwick.ac.uk/api/v1.0/lookup?barcode=SAL_HB2028AA_ST”, “create_time”: “2017-04-13 11:02:00.465841”, “info”: {
“lineage”: “”, “st_complex”: “4”, “subspecies”: “”}, “reference”: {
“lab_contact”: “public”, “refstrain”: “SAL_RA9255AA_AS”, “source”: “mlst.warwick.ac.uk”}, “scheme”: “UoW”, “st_barcode”: “SAL_HB2028AA_ST”
}
], “links”: {
- “paging”: {
- “next”: “https://enterobase.warwick.ac.uk/api/v2.0/senterica/MLST_Achtman/sts?limit=5&offset=5&show_alleles=false&scheme=MLST_Achtman&reldate=20”
}, “records”: 5, “total_records”: 28
}
}¶
Note that as discussed in [the notes about downloading schemes](api_download_schemes) it is inadvisable to download the ST profiles in their entirety using the above method, rather to download a tarball with the daily dump of all data and update with new information at regular intervals using queries like the one above as is described on [that page](api_download_schemes). # The traces query method #
Refer to interactive documentation : https://enterobase.warwick.ac.uk/api/v2.0/swagger-ui#!/Traces
The traces
query method shows metadata such as read length, accession number and sequencing platform
for sequenced reads.
An example of this type of query in the Swagger UI has “database” set to “senterica” and “barcode” set to “SAL_KA1677AA_TR” equivalent to a request to the URL
`
https://enterobase.warwick.ac.uk/api/v2.0/senterica/traces?barcode=SAL_KA1677AA_TR
`
This obtains the result
``` {
- “Traces”: [
- {
- “lastmodified”: “2017-05-04T09:35:53.574967+00:00”, “trace_barcode”: “SAL_KA1677AA_TR”
}
], “links”: {
“paging”: {}, “records”: 1, “total_records”: 1}