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.

Four 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

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://v3.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://v3.boldsystems.org/index.php/API_Public/specimen?taxon=Aves&geo=Costa%20Rica&format=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.

format
(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:

  • format=tsv
  • format=xml

Sequence Data Retrieval

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

Base URL: http://v3.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://v3.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

format

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://v3.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://v3.boldsystems.org/index.php/API_Public/combined?taxon=Mammalia&geo=Canada&format=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

format
(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:

  • format=tsv
  • format=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.

Base URL: http://v3.boldsystems.org/index.php/API_Public/trace?

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 Example: To retrieve traces belonging to the genus Bombus, stored in the institution York University. (Example of results available in TAR here) 
http://v3.boldsystems.org/index.php/API_Public/trace?taxon=Bombus&institutions=York%20University

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

format

Returns the traces compressed in a TAR file. (no parameter necessary)