PBDB Data Service: List of taxa

PBDB Data Service 1.2 v2 > Taxonomic names > List of taxa

DESCRIPTION

This operation returns information about multiple taxonomic names, selected according to the criteria you specify. This operation could be used to query for all of the children or parents of a given taxon, among other operations.

USAGE

Here are some usage examples:

PARAMETERS

The following parameters are used to select the base set of taxonomic names to return. Any query using this operation must include exactly one of the parameters from the following list. If you wish to download the entire taxonomy, use all_taxa or all_records and see also the limit parameter. If you want to select taxa that are mentioned in particular bibliographic references, use the taxa/byref operation instead.

taxon_name	For each of the specified names, select the taxon that most closely matches it. You may specify more than one name, separated by commas. The characters % . and _ may be used as wildcards, however only one match will be returned for each name. Whenever more than, one taxon matches a given name, the one with the most occurrences in the database will be selected. You may instead use the alias name for this parameter. If you wish to select by common name instead of scientific name, include the parameter common as well. See the documentation page on specifying taxonomic names for more information.
match_name	Selects all taxonomic names matching the given pattern. The characters % . and _ may be used as wildcards. The first two will match any number of characters, while the last will match any single character. If you wish to select by common name instead of scientific name, include the parameter common as well.
base_name	Selects the valid taxonomic name most closely matching the specified name(s), plus all synonyms and subtaxa. You can specify more than one name, separated by commas. This is a shortcut, equivalent to specifying taxon_name and rel=all_children. If you wish to select by common name instead of scientific name, include the paramter common as well.
taxon_id	Selects the taxonomic names represented by the specified identifier(s). You may specify more than one, separated by commas. You may instead use the alias id for this parameter.
base_id	Selects the valid taxonomic names most closely matching the specified identifier(s), plus all synonyms and subtaxa. You can specify more than one identifier, separated by commas. This is a shortcut, equivalent to specifying taxon_id and rel=all_children.
ref_id	Selects the taxonomic names for which the specified reference(s) are the primary source.
all_taxa	Selects the current variant of every taxonomic name from the database. Be careful when using this, since the full result set if you don't specify any other parameters can exceed 80 megabytes. This parameter does not need any value.
all_records	Selects all taxonomic names from the database, including all variants. This is equivalent to specifying all_taxa&variant=all. Be careful when using this, since the full result set if you don't specify any other parameters can exceed 80 megabytes. This parameter does not need any value.

The following parameters modify the selection of taxonomic names:

exclude_id

Excludes the taxonomic subtree(s) corresponding to the taxon or taxa represented by the specified identifier(s). This is only relevant if you also specify base_name, base_id, or rel=all_children. If you are using base_name, you can also exclude subtaxa by name using the ^ symbol, as in dinosauria^aves or osteichthyes^tetrapoda.

immediate

If you specify this parameter along with base_name or base_id, then only children of the specified taxa are listed, and not synonyms or the children of synonyms. If you specify this parameter along with rel=parent or rel=all_parents, then the taxa immediately containing the matching taxa are returned even if they are junior synonyms.

common

This parameter indicates that name lookup should be done on common names instead of (or in addition to) scientific names. The value should be one or more two-character language codes as a comma-separated list, indicating which language(s) to match. You can also include the value S, to match scientific names as well as common names. For example: /data1.2/taxa/list.json?taxon_name=whale&common=EN

taxon_status

Selects only names that have the specified status. The default is all. Accepted values include:

all	Select all taxonomic names matching the other specified criteria. This is the default.
valid	Select only taxonomically valid names
accepted	Select only taxonomically valid names that are not junior synonyms
junior	Select only taxonomically valid names that are junior synonyms
invalid	Select only taxonomically invalid names, e.g. nomina dubia

You can select names that are related to the ones you specify, by using the following parameter:

rel

Indicates the relationship between the names that match your specification and the names to be selected. Accepted values include:

exact	Select the matching taxonomic name(s) themselves. This is the default if you use taxon_name, taxon_id, or match_name.
current	Select the currently accepted variant of each of the matching taxonomic name(s).
variants	Select all variants of the matching taxonomic name(s) that are known to this database. These may be variant spellings, or previous ranks. For example a taxon currently ranked as a suborder might have been previously ranked as an order, which would count as a different variant.
senior	Select the senior name corresponding to each matching taxonomic name. If a matching name is a junior synonym then the corresponding senior synonym will be returned. Otherwise, the currently accepted variant of the matching name will be returned.
accepted	Select the accepted name corresponding to each matching taxonomic name. If a matching name is a junior synonym, its senior synonym will be returned. If a matching name is invalid (i.e. a nomen dubium or nomen nudum) then the corresponding valid name will be returned. Otherwise, the currently accepted variant of the matching name will be returned.
synonyms	Select all synonyms of the matching name(s) which are known to this database.
children	Select all the taxa immediately contained within each matching taxon and within all synonymous taxa.
all_children	Select all taxa contained within each matching taxon and within all synonymous taxa. This selects an entire subtree of the taxonomic hierarchy. It is the default if you use base_name or base_id.
parent	Select the taxon immediately containing each matching taxon. If an immediate parent taxon is a junior synonym, the corresponding senior synonym will be returned. You can also use the alias senpar.
immpar	Select the taxon immediately containing each matching taxon, even if it is a junior synonym. This is equivalent to rel=parent&immediate.
all_parents	Select all taxa that contain any of the matching taxa. The senior synonym of each name will be returned, unless you also specify. the parameter immediate in which case each actual containing taxon will be returned even if it is a junior synonym.
common	Select the most specific taxon that contains all of the matching taxa.

variant

If you specify variant=all, then all variants of the selected names will be returned. This may include variant spellings, previous combinations, and previous ranks. You may use this in combination with any of the other parameters and relationship values. If not specified, then whichever variants are selected by the other parameters will be returned.

The following parameters further filter the list of selected records:

rank

Select only taxonomic names at the specified rank, e.g. genus.

extant

Select only extant or non-extant taxa. Accepted values are: yes, no.

pres

This parameter indicates whether to select ichnotaxa, form taxa, or regular taxa. The default is all, which will select all taxa that meet the other specified criteria. You can specify one or more of the following values as a list:

regular	Select regular taxa
form	Select form taxa
ichno	Select ichnotaxa
all	Select all taxa

max_ma

Select only taxa which have at least one occurrence in the database no older than the given age in Ma. Please note that this does not necessarily correspond to the actual first appearance of these taxa in the fossil record, just in that portion of the fossil record that has been entered into the database. By using the parameters max_ma and min_ma together, you can select only taxa whose appearance in the database overlaps a particular age range. Note that this may include taxa without an actual occurrence in that age range. If you wish to select only taxa which actually have a recorded occurrence in a particular time range, or if you wish to use a time resolution rule other than overlap, use the occs/taxa operation instead.

min_ma

Select only taxa which have at least one occurence in the database no younger than the given age in Ma. See max_ma above.

interval

Select only taxa whose occurrences in the database overlap the specified time interval or intervals, given by name. You may give more than one interval name, separated either by hyphens or commas. The selected time range will stretch from the beginning of the oldest specified interval to the end of the youngest specified, with no gaps. Note that this may include taxa without any occurrences that actually fall within the specified interval or intervals.

interval_id

Select only taxa whose occurrences in the database overlap the specified time interval or intervals, given by identifier. See the parameter interval above.

depth

Select only taxa no more than the specified number of levels below or above the base taxon or taxa in the taxonomic hierarchy. You can use this parameter if you want to print out a portion of the taxonomic hierarchy centered upon a higher taxon wihtout printing out its entire subtree.

taxa_created_before

Select only records associated with taxa that were created before the specified date or date/time.

taxa_created_after

Select only records associated with taxa that were created on or after the specified date or date/time.

taxa_modified_before

Select only records associated with taxa that were last modified before the specified date or date/time.

taxa_modified_after

Select only records associated with taxa that were modified on or after the specified date or date/time.

taxa_authorized_by

Select only records associated with taxa that were authorized by the specified person, indicated by name or identifier

taxa_entered_by

Select only records associated with taxa that were entered by the specified person, indicated by name or identifier

taxa_modified_by

Select only records associated with taxa that were modified by the specified person, indicated by name or identifier

taxa_touched_by

Select only records associated with taxa that were either authorized, entered or modified by the specified person, indicated by name or identifier

taxa_authent_by

Select only records associated with taxa that were authorized or entered by the specified the specified person, indicated by name or identifier

The following parameters can be used to generate data archives. The easiest way to do this is by using the download generator form.

archive_title	A value for this parameter directs that an archive be created with the specified title unless one already exists.
archive_replace	A true value for this parameter directs that if there is an existing archive with the specified title then its contents should be replaced by the output of the current request. Without this parameter, the error code E_EXISTING will be returned if the specified title matches an existing record. If the existing record has a DOI, the error E_IMMUTABLE will be returned and this cannot be overridden.
archive_authors	The value of this parameter, if any, is put into the 'authors' field of the created or updated archive record.
archive_desc	The value of this parameter, if any, is put into the 'description' field of the created or updated archive record.

The following parameters indicate which information should be returned about each resulting name, and the order in which you wish the records to be returned.

show

This parameter is used to select additional blocks of information to be returned along with the basic record for each taxon. Its value should be one or more of the following, separated by commas:

full	This is a shortcut for including all of the information that defines this record. Currently, this includes the following blocks: attr, app, common, parent size, class, ecospace, otaph, etbasis, refattr. If we subsequently add new data fields to this record then full will include those as well. So if you are publishing a URL, it might be a good idea to include show=full.
attr	The attribution of this taxonomic name (author and year)
app	The age of first and last appearance of this taxon from all of the occurrences recorded in this database
common	The common name of this taxon, if one is entered in the database.
parent	If the classification of this taxon has been entered into the database, the name of the parent taxon, or its senior synonym if there is one.
immparent	You can use this instead of parent if you wish to know the immediate parent taxon. If the immediate parent is a junior synonym, both it and its senior synonym will be displayed.
acconly	Only return accepted names, and suppress the fields difference, accepted_name, accepted_rank, and accepted_no, because they are only relevant for non-accepted names.
size	The number of subtaxa appearing in this database, including the taxon itself.
class	The classification of this taxon: phylum, class, order, family, genus. Also includes the type taxon, if one is entered in the database. This information is also included in the nav block, so do not specify both at once.
classext	Like class, but also includes the relevant taxon identifiers.
subcounts	The number of subtaxa known to this database, summarized by rank.
ecospace	Information about ecological space that this organism occupies or occupied. This has only been filled in for a relatively few taxa. Here is a list of values.
ttaph	Information about the taphonomy of this organism. You can also use the alias taphonomy. Here is a list of values.
etbasis	Annotates the output block ecospace, indicating at which taxonomic level each piece of information was entered.
seq	The sequence numbers that mark this taxon's position in the tree.
img	The identifier of the image (if any) associated with this taxon. These images are sourced from phylopic.org.
ref	The reference from which this taxonomic name was entered, as formatted text.
refattr	The author(s) and year of publication of the reference. Note that this may be different from the attribution of the name itself, if the reference is a secondary source.
ent	The identifiers of the people who authorized, entered and modified this record
entname	The names of the people who authorized, entered and modified this record
crmod	The created and modified timestamps for the collection record

order

Specifies the order in which the results are returned. You can specify multiple values separated by commas, and each value may be appended with .asc or .desc. The default is hierarchy. Accepted values are:

hierarchy	Results are ordered hierarchically by taxonomic identification. The order of sibling taxa is arbitrary, but children will always follow after parents.
ref	Results are ordered by reference id, so that taxa entered from the same reference are listed together.
name	Results are ordered alphabetically by taxon name.
firstapp	Results are ordered chronologically by first appearance, oldest to youngest unless you add .asc
lastapp	Results are ordered chronologically by last appearance, oldest to youngest unless you add .asc
agespan	Results are ordered based on the difference between the first and last appearances, starting with occurrences with the smallest spread (most precise temporal resolution) unless you add .desc
n_occs	Results are ordered by the number of fossil occurrences of this taxon entered in this database, largest to smallest unless you add .asc
pubyr	Results are ordered by the year in which the name was first published, oldest first unless you add .asc
author	Results are ordered alphabetically by the last name of the primary author
size	Results are ordered by the number of contained subtaxa, largest to smallest unless you add .asc
extsize	Results are ordered by the number of extant subtaxa, largest to smallest unless you add .asc
extant	Results are ordered by whether or not the taxon is extant, with extant ones first unless you add .asc
created	Results are ordered by the date the record was created, most recent first unless you add .asc.
modified	Results are ordered by the date the record was last modified most recent first unless you add .asc

You can also use any of the special parameters with this request.

METHODS

This data service accepts the following HTTP methods: GET, HEAD

RESPONSE

The response to an HTTP request with this operation will consist of fields from the following list. The block basic is always present. The others may be selected using the parameter show.

Field name

Block

Description

pbdb

com

orig_no

oid

basic

A unique identifier for this taxonomic name

taxon_no

vid

basic

A unique identifier for the selected variant of this taxonomic name. By default, this is the variant currently accepted as most correct.

record_type

typ

basic

The type of this object: txn for a taxon.

flags

flg

basic

This field will be empty for most records. Otherwise, it will contain one or more of the following letters:

B	This taxon is one of the ones specified explicitly in the query. If the result is a subtree, this represents the 'base'.
E	This taxon was specified in the query as an exclusion.
V	This taxonomic name is a variant that is not currently accepted.
I	This taxon is an ichnotaxon.
F	This taxon is a form taxon.

taxon_rank

rnk

basic

The rank of this taxon, ranging from subspecies up to kingdom

taxon_name

nam

basic

The scientific name of this taxon

taxon_attr

att

attr

The attribution (author and year) of this taxonomic name

common_name

nm2

common, full

The common (vernacular) name of this taxon, if any

difference

tdf

basic

If this name is either a junior synonym or is invalid for some reason, this field gives the reason. The fields accepted_no and accepted_name then specify the name that should be used instead.

tax_status

n/a

basic

The taxonomic status of this name, in the Darwin Core vocabulary. This field only appears if that vocabulary is selected.

nom_status

n/a

basic

The nomenclatural status of this name, in the Darwin Core vocabulary. This field only appears if that vocabulary is selected.

accepted_no

acc

basic

If this name is either a junior synonym or an invalid name, this field gives the identifier of the accepted name to be used in its place. Otherwise, its value will be the same as orig_no. In the compact vocabulary, this field will be omitted in that case.

accepted_rank

acr

basic

If accepted_no is different from orig_no, this field gives the rank of the accepted name. Otherwise, its value will be the same as taxon_rank. In the compact voabulary, this field will be omitted in that case.

accepted_name

acn

basic

If accepted_no is different from orig_no, this field gives the accepted name. Otherwise, its value will be the same as taxon_name. In the compact vocabulary, this field will be omitted in that case.

parent_no

par

basic

The identifier of the parent taxon, or of its senior synonym if there is one. This field and those following are only available if the classification of this taxon is known to the database.

parent_name

prl

parent, immparent

The name of the parent taxon, or of its senior synonym if there is one.

immpar_no

ipn

immparent

The identifier of the immediate parent taxon, even if it is a junior synonym.

immpar_name

ipl

immparent

The name of the immediate parent taxon, even if it is a junior synonym.

container_no

ctn

basic

The identifier of a taxon from the result set containing this one, which may or may not be the parent. This field will only appear in the result of the occs/taxa operation, where no base taxon is specified. The taxa reported in this case are the "classical" ranks, rather than the full taxonomic hierarcy.

ref_author

aut

refattr, refattr

The author(s) of the reference from which this name was entered. Note that the author of the name itself may be different if the reference is a secondary source.

ref_pubyr

pby

refattr, refattr

The year of publication of the reference from which this name was entered. Note that the publication year of the name itself may be different if the reference is a secondary source.

reference_no

rid

basic

The identifier of the reference from which this name was entered.

is_extant

ext

basic

True if this taxon is extant on earth today, false if not, not present if unrecorded

n_occs

noc

basic

The number of fossil occurrences in this database that are identified as belonging to this taxon or any of its subtaxa.

firstapp_max_ma

fea

app

The early age bound for the first appearance of this taxon in the database

firstapp_min_ma

fla

app

The late age bound for the first appearance of this taxon in the database

lastapp_max_ma

lea

app

The early age bound for the last appearance of this taxon in the database

lastapp_min_ma

lla

app

The late age bound for the last appearance of this taxon in the database

early_interval

tei

app

The name of the interval in which this taxon first appears, or the start of its range.

late_interval

tli

app

The name of the interval in which this taxon last appears, if different from early_interval.

taxon_size

siz

size

The total number of taxa in the database that are contained within this taxon, including itself

extant_size

exs

size

The total number of extant taxa in the database that are contained within this taxon, including itself

phylum

phl

class

The name of the phylum in which this taxon is classified

phylum_no

phn

classext

The identifier of the phylum in which this taxon is classified. This is only included with the block classext.

class

cll

class

The name of the class in which this taxon is classified

class_no

cln

classext

The identifier of the class in which this taxon is classified. This is only included with the block classext.

order

odl

class

The name of the order in which this taxon is classified

order_no

odn

classext

The identifier of the order in which this occurrence is classified. This is only included with the block classext.

family

fml

class

The name of the family in which this taxon is classified

family_no

fmn

classext

The identifier of the family in which this occurrence is classified. This is only included with the block classext.

genus

gnl

class

The name of the genus in which this taxon is classified. A genus may be listed as occurring in a different genus if it is a junior synonym; a species may be listed as occurring in a different genus than its name would indicate if its genus is synonymized but no synonymy opinion has been entered for the species.

genus_no

gnn

classext

The identifier of the genus in which this occurrence is classified. This is only included with the block classext.

subgenus_no

sgn

classext

The identifier of the subgenus in which this occurrence is classified, if any. This is only included with the block classext.

type_taxon

ttl

class

The name of the type taxon for this taxon, if known.

type_taxon_no

ttn

classext

The identifier of the type taxon for this taxon, if known.

n_orders

odc

subcounts

The number of orders within this taxon. For lists of taxa derived from a set of occurrences, this will be the number of orders that appear within that set. Otherwise, this will be the total number of orders within this taxon that are known to the database.

n_families

fmc

subcounts

The number of families within this taxon, according to the same rules as n_orders above.

n_genera

gnc

subcounts

The number of genera within this taxon, according to the same rules as n_orders above.

n_species

spc

subcounts

The number of species within this taxon, according to the same rules as n_orders above.

taxon_environment

jev

ecospace

The general environment or environments in which this life form is found. See ecotaph vocabulary.

environment_basis

jec

ecospace

Specifies the taxon from which the environment information is inherited.

motility

jmo

ecospace

Whether the organism is motile, attached and/or epibiont, and its mode of locomotion if any. See ecotaph vocabulary.

motility_basis

jmc

etbasis

Specifies the taxon for which the motility information was set. The taphonomy and ecospace information are inherited from parent taxa unless specific values are set.

life_habit

jlh

ecospace

The general life mode and locality of this organism. See ecotaph vocabulary.

life_habit_basis

jhc

etbasis

Specifies the taxon for which the life habit information was set. See motility_basis above. These fields are only included if the ecospace block is also included.

vision

jvs

ecospace

The degree of vision possessed by this organism. See ecotaph vocabulary.

vision_basis

jvc

etbasis

Specifies the taxon for which the vision information was set. See motility_basis above. These fields are only included if the ecospace block is also included.

diet

jdt

ecospace

The general diet or feeding mode of this organism. See ecotaph vocabulary.

diet_basis

jdc

etbasis

Specifies the taxon for which the diet information was set. See motility_basis above. These fields are only included if the ecospace block is also included.

reproduction

jre

ecospace

The mode of reproduction of this organism. See ecotaph vocabulary.

reproduction_basis

jrc

etbasis

Specifies the taxon for which the reproduction information was set. See motility_basis above. These fields are only included if the ecospace block is also included.

ontogeny

jon

ecospace

Briefly describes the ontogeny of this organism. See ecotaph vocabulary.

ontogeny_basis

joc

etbasis

Specifies the taxon for which the ontogeny information was set. See motility_basis above. These fields are only included if the ecospace block is also included.

ecospace_comments

jcm

ecospace

Additional remarks about the ecospace, if any.

composition

jco

ttaph

The composition of the skeletal parts of this organism. See taphonomy vocabulary.

architecture

jsa

ttaph

An indication of the internal skeletal architecture. See taphonomy vocabulary.

thickness

jth

ttaph

An indication of the relative thickness of the skeleton. See taphonomy vocabulary.

reinforcement

jsr

ttaph

An indication of the skeletal reinforcement, if any. See taphonomy vocabulary.

taphonomy_basis

jtc

etbasis

Specifies the taxon for which the taphonomy information was set. See motility_basis above. These fields are only included if the otaph block is also included.

lft

lsq

seq

This number gives the taxon's position in a preorder traversal of the taxonomic tree.

rgt

rsq

seq

This number greater than or equal to the maximum of the sequence numbers of all of this taxon's subtaxa, and less than the sequence of any succeeding taxon in the sequence. You can use this, along with lft, to determine subtaxon relationships. If the pair lft,rgt for taxon <A> is bracketed by the pair lft,rgt for taxon <B>, then A is a subtaxon of B.

image_no

img

If this value is non-zero, you can use it to construct image URLs using taxa/thumb and taxa/icon.

primary_reference

ref

The primary reference associated with this record (as formatted text)

authorizer_no

ati

ent, entname

The identifier of the person who authorized the entry of this record

enterer_no

eni

ent, entname

The identifier of the person who actually entered this record.

modifier_no

mdi

ent, entname

The identifier of the person who last modified this record, if it has been modified.

authorizer

ath

entname

The name of the person who authorized the entry of this record

enterer

ent

entname

The name of the person who actually entered this record

modifier

mdf

entname

The name of the person who last modified this record, if it has been modified.

created

dcr

crmod

The date and time at which this record was created.

modified

dmd

crmod

The date and time at which this record was last modified.

FORMATS

The following response formats are available for this operation. You must select the desired format for a request by adding the appropriate suffix to the URI path.

Format	Suffix	Documentation
JSON	.json	JSON format
Comma-separated text	.txt	Text formats
Comma-separated text	.csv	Text formats
Tab-separated text	.tsv	Text formats

VOCABULARIES

The following response vocabularies are available for this operation. If you wish your responses to be expressed in a vocabulary other than the default for your selected format, you can use the vocab parameter with the appropriate vocabulary name.

Vocabulary	Name	Default for	Description
PaleobioDB field names	pbdb	txt, csv, tsv	The PBDB vocabulary is derived from the underlying field names and values in the database, augmented by a few new fields. For the most part any response that uses this vocabulary will be directly comparable to downloads from the PBDB Classic interface. This vocabulary is the default for text format responses.
Compact field names	com	json	The Compact vocabulary is a set of 3-character field names designed to minimize the size of the response message. This is the default for JSON format responses. Some of the field values are similarly abbreviated, while others are conveyed in their entirety. For details, see the documentation for the individual response fields.

This service is provided by the Paleobiology Database, hosted by the Department of Geoscience at the University of Wisconsin-Madison.

If you have questions about this data service, or wish to report a bug, please contact the database administrator at admin@paleobiodb.org

PBDB Data Service: List of taxa

PBDB Data Service 1.2 v2 > Taxonomic names > List of taxa

DESCRIPTION

USAGE

PARAMETERS

METHODS

RESPONSE

FORMATS

VOCABULARIES

CONTACT