REST API for Public Data Portal

The BOLD Web Services provide the ability to download specimen, sequence and trace data from the Public Data Portal.

4 API Web Services are described below, including the outputs, sample URL and various parameters (inputs) available for each service.

General Format Notes: Each service can accept multiple input parameters, ampersand ('&') delimited, treating the parameters as a logical "AND" clause. All input parameters can accept multiple string values, pipe ('|') delimited, unless otherwise noted. These string values are treated as a logical "OR" clause. All spaces in the URLs need to be encoded.

Web Services Endpoints for retrieving data from the Public Data Portal:

Specimen Data Retrieval
Sequence Data Retrieval
Full Data Retrieval (Specimen + Sequence)
Trace File Data Retrieval (Electropherogram)

Specimen Data Retrieval

Description: Users can query the system to retrieve matching specimen data records for a combination of parameters as are described in the table below.

Base URL: http://www.boldsystems.org/index.php/API_Public/specimen/?

Results: TSV or XML file consisting of the Voucher, Taxonomic, Specimen and Collection data for each record.

Example: To retrieve specimen data records for taxon Aves from Costa Rica in TSV format. (Example of first record available in TSV here)

http://www.boldsystems.org/index.php/API_Public/specimen/?taxon=Aves&geo=Costa%20Rica&specimen_download=tsv

Specimen Parameters	Description
taxon	Returns all records containing matching taxa, defined in a pipe delimited list.(spaces need to be encoded) Taxa includes scientific names at phylum, class, order, family, subfamily, genus, and species levels. Examples: taxon=Bos taurus returns all records matching the taxon Bos taurus. taxon=Aves\|Reptilia returns all records matching the taxa Aves or Reptilia taxon=root returns all records from the root of the taxonomic tree
ids	Returns all records containing matching IDs, defined in a pipe delimited list.(spaces need to be encoded) IDs include Sample IDs, Process IDs, Museum IDs and Field IDs. Examples: ids=ACRJP618-11\|ACRJP619-11 returns records matching these Process IDs. ids=Example 10\|Example 11\|Example 12 returns records matching these Sample IDs.
bin	Returns all records contained in matching BINs, defined in a pipe delimited list. A BIN is defined by a Barcode Index Number URI. Example: bin=BOLD:AAA5125\|BOLD:AAA5126 returns records matching these BIN URIs.
container	Returns all records contained in matching projects or datasets, in a pipe delimited list. Containers include project codes and dataset codes. Examples: container=ACRJP\|ACRJI returns records contained within matching projects. container=DS-EZROM returns records contained within the matching dataset.
institutions	Returns all records stored in matching institutions, defined in a pipe delimited list. Institutions are the Specimen Storing Site. (spaces need to be encoded) Example: institutions=Biodiversity Institute of Ontario\|York University returns records for specimens stored within matching institutions.
researchers	Returns all records containing matching researcher names, defined in a pipe delimited list. Researchers include collectors and specimen identifiers. (spaces need to be encoded) Example: researchers=Thibaud Decaens\|Rodolphe Rougerie returns records for specimens collected or identified by the matching researchers.
geo	Returns all records collected in matching geographic sites, defined in a pipe delimited list. Geographic sites includes countries and province/states. (spaces need to be encoded) Example: geo=Canada\|Alaska returns records for specimens collected in the matching geographic sites.
specimen_download (optional)	Returns all records in one of the specified formats. By default it will return in xml format (only one format can be selected per query) Options: specimen_download=tsv specimen_download=xml

Sequence Data Retrieval

Description: Users can query the system to retrieve matching sequencesfor a combination of parameters as are described in the table below.

Base URL: http://www.boldsystems.org/index.php/API_Public/sequence/?

Results: FASTA file consisting of sequences.

The fields returned for each sequence (pipe delimited in the FASTA header) are: processid identification marker accession

Example: To retrieve records for taxon Chordata, collected in Florida, belonging to the institution Smithsonian Institution. (Example of first record available in FASTA here)

http://www.boldsystems.org/index.php/API_Public/sequence/?taxon=Chordata&geo=Florida&institutions=Smithsonian%20Institution

Sequence Parameters	Description
taxon	Returns all records containing matching taxa, defined in a pipe delimited list. Taxa includes the ranks of phylum, class, order, family, subfamily, genus, and species. Examples: taxon=Bos taurus returns all records containing Bos taurus. taxon=Aves\|Reptilia returns all records containing Aves or Reptilia.
ids	Returns all records containing matching IDs, defined in a pipe delimited list. IDs include Sample IDs, Process IDs, Museum IDs and Field IDs. Examples: ids=ACRJP618-11\|ACRJP619-11 returns records containing matching Process IDs. ids=Example 10\|Example 11\|Example 12 returns records containing matching Sample IDs.
bin	Returns all records contained in matching BINs, defined in a pipe delimited list. A BIN is defined by a Barcode Index Number URI. Example: bin=BOLD:AAA5125\|BOLD:AAA5126 returns records containing matching BIN URIs.
container	Returns all records contained in matching projects or datasets, in a pipe delimited list. Containers include project codes and dataset codes Examples: container=ACRJP\|ACRJI returns records contained within matching projects. container=DS-EZROM returns records contained within the matching dataset.
institutions	Returns all records stored in matching institutions, defined in a pipe delimited list. Institutions are the Specimen Storing Site. (spaces need to be encoded) Example: institutions=Biodiversity Institute of Ontario\|York University returns records for specimens stored within matching institutions.
researchers	Returns all records containing matching researcher names, defined in a pipe delimited list. Researchers include collectors and specimen identifiers. (spaces need to be encoded) Example: researchers=Thibaud Decaens\|Rodolphe Rougerie returns records for specimens collected or identified by the matching researchers.
geo	Returns all records collected in matching geographic sites, defined in a pipe delimited list. Geographic sites includes countries and province/states. (spaces need to be encoded) Example: geo=Canada\|Alaska returns records for specimens collected in the matching geographic sites.
marker	Returns all records containing matching marker codes defined in a pipe delimited list. Examples: marker=matK\|rbcL marker=COI-5P
sequence_download	Returns the sequences in a FASTA formatted file. (no parameter necessary)

Full Data Retrieval (Specimen + Sequence)

Description: Users can query the system to retrieve matching specimen data and sequence records for a combination of parameters as are described in the table below.

Base URL: http://www.boldsystems.org/index.php/API_Public/combined/?

Results: TSV or XML file consisting of the Voucher, Taxonomic, Specimen, Collection data and Sequence for each record.
FASTA is not a supported file format for the Combined Specimen and Sequence Service.

Example: To retrieve Specimen Data and Sequences for records belonging to the taxon Mammalia, collected in Canada, in an TSV format. (Example of first record available in TSV here)

http://www.boldsystems.org/index.php/API_Public/combined?taxon=Mammalia&geo=Canada&combined_download=tsv

Combined Parameters	Description
taxon	Returns all records containing matching taxa defined in a pipe delimited list. Taxa includes the ranks of phylum, class, order, family, subfamily, genus, and species. Examples: taxon=Bos taurus returns all records containing Bos taurus. taxon=Aves\|Reptilia returns all records containing Aves or Reptilia.
ids	Returns all records containing matching IDs defined in a pipe delimited list. IDs include Sample IDs, Process IDs, Museum IDs and Field IDs. Examples: ids=ACRJP618-11\|ACRJP619-11 returns records containing matching Process IDs. ids=Example 10\|Example 11\|Example 12 returns records containing matching Sample IDs.
bin	Returns all records contained in matching BINs defined in a pipe delimited list. A BIN is defined by a Barcode Index Number URI. Example: bin=BOLD:AAA5125\|BOLD:AAA5126 returns records containing matching BIN URIs.
container	Returns all records contained in matching projects or datasets in a pipe delimited list. Containers include project codes and dataset codes Examples: container=ACRJP\|ACRJI returns records contained within matching projects. container=DS-EZROM returns records contained within the matching dataset.
institutions	Returns all records stored in matching institutions, defined in a pipe delimited list. Institutions are the Specimen Storing Site. (spaces need to be encoded) Example: institutions=Biodiversity Institute of Ontario\|York University returns records for specimens stored within matching institutions.
researchers	Returns all records containing matching researcher names, defined in a pipe delimited list. Researchers include collectors and specimen identifiers. (spaces need to be encoded) Example: researchers=Thibaud Decaens\|Rodolphe Rougerie returns records for specimens collected or identified by the matching researchers.
geo	Returns all records collected in matching geographic sites, defined in a pipe delimited list. Geographic sites includes countries and province/states. (spaces need to be encoded) Example: geo=Canada\|Alaska returns records for specimens collected in the matching geographic sites.
marker	Returns all records containing matching marker codes defined in a pipe delimited list. Examples: marker=matK\|rbcL marker=COI-5P
combined_download (optional)	Returns all records in one of the specified formats. By default it will return in xml format (only one format can be selected per query) Options: combined_download=tsv combined_download=xml

Trace File Data Retrieval

Description: Users can query the system to retrieve matching trace files for a combination of parameters as are described in the table below.

Results: TAR file consisting of compressed Trace Files (traces in either .ab1 or .scf format) along with a file listing the Process ID, taxon and marker for each Trace File included.

Trace File Parameters	Description
taxon	Returns all traces containing matching taxa defined in a pipe delimited list. Taxa includes the ranks of phylum, class, order, family, subfamily, genus, and species. Examples: taxon=Bos taurus returns all records containing Bos taurus. taxon=Aves\|Reptilia returns all records containing Aves or Reptilia.
ids	Returns all traces containing matching IDs defined in a pipe delimited list. IDs include Sample IDs, Process IDs, Museum IDs and Field IDs. Examples: ids=ACRJP618-11\|ACRJP619-11 returns records containing matching Process IDs. ids=Example 10\|Example 11\|Example 12 returns records containing matching Sample IDs.
bin	Returns all traces contained in matching BINs defined in a pipe delimited list. A BIN is defined by a Barcode Index Number URI. Example: bin=BOLD:AAA5125\|BOLD:AAA5126 returns records containing matching BIN URIs.
container	Returns all traces contained in matching projects or datasets in a pipe delimited list. Containers include project codes and dataset codes Examples: container=ACRJP\|ACRJI returns records contained within matching projects. container=DS-EZROM returns records contained within the matching dataset.
institutions	Returns all records stored in matching institutions, defined in a pipe delimited list. Institutions are the Specimen Storing Site. (spaces need to be encoded) Example: institutions=Biodiversity Institute of Ontario\|York University returns records for specimens stored within matching institutions.
researchers	Returns all records containing matching researcher names, defined in a pipe delimited list. Researchers include collectors and specimen identifiers. (spaces need to be encoded) Example: researchers=Thibaud Decaens\|Rodolphe Rougerie returns records for specimens collected or identified by the matching researchers.
geo	Returns all records collected in matching geographic sites, defined in a pipe delimited list. Geographic sites includes countries and province/states. (spaces need to be encoded) Example: geo=Canada\|Alaska returns records for specimens collected in the matching geographic sites.
marker	Returns all traces containing matching marker codes, defined in a pipe delimited list. Examples: marker=COI-5P marker=matK\|rbcL
trace_download	Returns the traces compressed in a TAR file. (no parameter necessary)