PBDB Data Service 1.1 v6 > Fossil occurrences > Lists of fossil occurrences

DESCRIPTION

This path returns information about multiple occurrences, selected according to the parameters you provide. Depending upon which output blocks you select, the response will contain some fields describing the occurrences and some describing the collections to which they belong.

USAGE

Here are some usage examples:

PARAMETERS

You can use the following parameters if you wish to retrieve information about a known list of occurrences or collections, or to filter a known list against other criteria such as location or time. Only the records which match the other parameters that you specify will be returned.

id

A comma-separated list of occurrence identifiers.

coll_id

A comma-separated list of collection identifiers. All occurrences associated with the specified collections are returned, provided they satisfy the other parameters given with this request.

The following parameters can be used to query for occurrences by a variety of criteria. Except as noted below, you may use these in any combination. These same parameters can all be used to select either occurrences, collections, or associated references or taxa.

clust_id

Return only records associated with the specified geographic clusters. You may specify one or more cluster ids, separated by commas.

taxon_name

Return only records associated with the specified taxonomic name(s). You may specify multiple names, separated by commas.

taxon_id

Return only records associated with the specified taxonomic name(s), specified by numeric identifier. You may specify multiple identifiers, separated by commas.

taxon_actual

If this parameter is specified, then only records that were actually identified with the specified taxonomic name and not those which match due to synonymy or other correspondences between taxa. This is a flag parameter, which does not need any value.

base_name

Return only records associated with the specified taxonomic name(s), including subtaxa. You may specify multiple names, separated by commas.

base_id

Return only records associated with the specified taxonomic name(s), specified by numeric identifier, including subtaxa. You may specify multiple identifiers, separated by commas. Note that you may specify at most one of 'taxon_name', 'taxon_id', 'base_name', 'base_id'.

exclude_id

Exclude any records whose associated taxonomic name is a child of the given name or names, specified by numeric identifier.

ident

If more than one taxonomic identification is recorded for some or all of the selected occurrences, this parameter specifies which are to be returned. Values include:

latest

Return the most recently published identification of each selected occurrence, as long as it matches the other specified criteria.

orig

Return the originally published identification of each selected occurence, as long as it matches the other specified criteria.

all

Return all matching identifications of each selected occurrence, each as a separate record

lngmin
lngmax

Return only records whose present longitude falls within the given bounds. If you specify one of these parameters then you must specify both. If you provide bounds outside of the range -180° to 180°, they will be wrapped into the proper range. For example, if you specify lngmin=270 & lngmax=360, the query will be processed as if you had said lngmin=-90 & lngmax=0 . In this case, all longitude values in the query result will be adjusted to fall within the actual numeric range you specified.

latmin

Return only records whose present latitude is at least the given value.

latmax

Return only records whose present latitude is at most the given value.

loc

Return only records whose present location (longitude and latitude) falls within the specified shape, which must be given in WKT format with the coordinates being longitude and latitude values.

plate

Return only records located on the specified geological plate(s), according to the primary paleogeographic model specified by the parameter pgm. The value of this parameter may be a comma-separated list of numeric plate identifiers.

pgm

Specify which paleogeographic model(s) to use when evaluating paleocoordinates. You may specify one or more from the following list, separated by commas. If you do not specify a value for this parameter, the default model is gplates.

scotese

Use the paleogeographic model defined by C. R. Scotese (2002), which is the one that this database has been using historically.

gplates

Use the paleogeographic model defined by the GPlates software from the EarthByte group. By default, the coordinates for each collection are calculated at the midpoint of its age range.

gp_early

Use the GPlates model, calculating the rotations at the early end of each collection's age range

gp_mid

A synonym for the value gplates.

gp_late

Use the GPlates model, calculating the rotations at the late end of each collection's age range

country

Return only records whose geographic location falls within the specified country or countries. The value of this parameter should be one or more two-character country codes as a comma-separated list.

continent

Return only records whose geographic location falls within the specified continent or continents. The value of this parameter should be a comma-separated list of continent codes.

formation

Return only records that fall within the named stratigraphic formation(s). You may specify more than one, separated by commas.

stratgroup

Return only records that fall within the named stratigraphic group(s). You may specify more than one, separated by commas.

member

Return only records that fall within the named stratigraphic member(s). You may specify more than one, separated by commas.

min_ma

Return only records whose temporal locality is at least this old, specified in Ma.

max_ma

Return only records whose temporal locality is at most this old, specified in Ma.

interval_id

Return only records whose temporal locality falls within the given geologic time interval, specified by numeric identifier.

interval

Return only records whose temporal locality falls within the named geologic time interval.

timerule

Resolve temporal locality according to the specified rule:

contain

Return only records whose temporal locality is strictly contained in the specified time range.

overlap

Return only records whose temporal locality overlaps the specified time range by any amount, no matter how small.

buffer

Return only records whose temporal locality overlaps the specified range and is contained within the specified time range plus a buffer on either side. If an interval from one of the timescales known to the database is given, then the default buffer will be the intervals immediately preceding and following at the same level. Otherwise, the buffer will default to 10 million years on either side. This can be overridden using the parameters earlybuffer and latebuffer. This is the default value for this option.

earlybuffer

Override the default buffer period for the beginning of the time range when resolving temporal locality. The value must be given in millions of years. This option not relevant if timerule is set to either contain or overlap.

latebuffer

Override the default buffer period for the end of the time range when resolving temporal locality. The value must be given in millions of years. This option not relevant if timerule is set to either contain or overlap.

created_before

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

created_after

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

modified_before

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

modified_after

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

authorized_by

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

entered_by

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

modified_by

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

touched_by

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

You can use the following parameters to select what information you wish to retrieve, and the order in which you wish to get the records:

show

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

coords

The latitude and longitude of this occurrence

attr

The attribution of the occurrence: the author name(s) from the primary reference, and the year of publication. If no reference is recorded for this occurrence, the reference for its collection is used.

ident

The actual taxonomic name by which this occurrence was identified

phylo

Additional information about the taxonomic classification of the occurence

genus

The genus (if known) and subgenus (if any) corresponding to each occurrence. This is a subset of the information provided by phylo.

loc

Additional information about the geographic locality of the occurrence

paleoloc

Information about the paleogeographic locality of the occurrence, evaluated according to the model specified by the parameter pgm.

prot

Indicate whether the containing collection is on protected land

time

Additional information about the temporal locality of the occurrence

strat

Basic information about the stratigraphic context of the occurrence.

stratext

Detailed information about the stratigraphic context of the occurrence. This includes all of the information from strat plus extra fields.

lith

Basic information about the lithological context of the occurrence.

lithext

Detailed information about the lithological context of the occurrence. This includes all of the information from lith plus extra fields.

abund

Information about the abundance of this occurrence in the collection

geo

Information about the geological context of the occurrence

rem

Any additional remarks that were entered about the containing collection.

ref

The primary reference for the occurrence, as formatted text. If no reference is recorded for this occurrence, the primary reference for its collection is returned.

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 occurrence 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. Accepted values are:

earlyage

Results are ordered chronologically by early age bound, oldest to youngest unless you add .asc

lateage

Results are ordered chronologically by late age bound, oldest to youngest unless you add .asc

agespan

Results are ordered based on the difference between the early and late age bounds, starting with occurrences with the smallest spread (most precise temporal resolution) unless you add .desc

taxon

Results are ordered hierarchically by taxonomic identification. The order of sibling taxa is arbitrary, but children will follow immediately after parents.

reso

Results are ordered according to the taxonomic rank to which they are resolved. Unless you add .desc, this would start with subspecies, species, genus, ...

formation

Results are ordered by the geological formation in which they were found, sorted alphabetically.

geogroup

Results are ordered by the geological group in which they were found, sorted alphabetically.

member

Results are ordered by the geological member in which they were found, sorted alphabetically.

plate

Results are ordered by the geological plate on which they are located, sorted numerically by identifier.

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

If no order is specified, results are sorted by occurrence identifier.

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 on this path will consist of fields from the following list. The block basic is always present. The others may be selected using the parameter show.

Field nameBlockDescription
pbdbcom
occurrence_no oid basic

A positive integer that uniquely identifies the occurrence

record_type typ basic

The type of this object: 'occ' for an occurrence

reid_no eid basic

If this occurrence was reidentified, a positive integer that uniquely identifies the reidentification

superceded sps basic

The value of this field will be true if this occurrence was later identified under a different taxon

collection_no cid basic

The identifier of the collection with which this occurrence is associated.

taxon_name tna basic

The taxonomic name by which this occurrence is identified

taxon_rank rnk basic

The taxonomic rank of the name, if this can be determined

taxon_no tid basic

The unique identifier of the identified taxonomic name. If this is empty, then the name was never entered into the taxonomic hierarchy stored in this database and we have no further information about the classification of this occurrence.

matched_name mna basic

The senior synonym and/or currently accepted spelling of the closest matching name in the database to the identified taxonomic name, if any is known, and if this name is different from the value of taxon_name.

matched_rank mra basic

The taxonomic rank of the matched name, if different from the value of taxon_rank

matched_no mid basic

The unique identifier of the closest matching name in the database to the identified taxonomic name, if any is known.

early_interval oei basic

The specific geologic time range associated with this collection (not necessarily a standard interval), or the interval that begins the range if late_interval is also given

late_interval oli basic

The interval that ends the specific geologic time range associated with this collection, if different from the value of early_interval

early_age eag basic

The early bound of the geologic time range associated with this occurrence (in Ma)

late_age lag basic

The late bound of the geologic time range associated with this occurrence (in Ma)

reference_no rid basic

The identifier(s) of the references from which this data was entered

lng lng coords

The longitude at which the occurrence was found (in degrees)

lat lat coords

The latitude at which the occurrence was found (in degrees)

genus_name idt ident

The taxonomic name (less species) by which this occurrence was identified. This is often a genus, but may be a higher taxon.

genus_reso rst ident

The resolution of this taxonomic name, i.e. sensu lato or aff.

subgenus_name idf ident

The subgenus name (if any) by which this occurrence was identified

subgenus_reso rsf ident

The resolution of the subgenus name, i.e. informal or n. subgen.

species_name ids ident

The species name (if any) by which this occurrence was identified

species_reso rss ident

The resolution of the species name, i.e. sensu lato or n. sp.

subgenus sgl phylo

The name of the genus in which this occurrence is classified

subgenus_no sgn phylo

The identifier of the genus in which this occurrence is classified

genus gnl phylo

The name of the genus in which this occurrence is classified

genus_no gnn phylo

The identifier of the genus in which this occurrence is classified

family fml phylo

The name of the family in which this occurrence is classified

family_no fmn phylo

The identifier of the family in which this occurrence is classified

order odl phylo

The name of the order in which this occurrence is classified

order_no odn phylo

The identifier of the order in which this occurrence is classified

class cll phylo

The name of the class in which this occurrence is classified

class_no cln phylo

The identifier of the class in which this occurrence is classified

phylum phl phylo

The name of the phylum in which this occurrence is classified

phylum_no phn phylo

The identifier of the phylum in which this occurrence is classified

subgenus sgl genus

The name of the genus in which this occurrence is classified

subgenus_no sgn genus

The identifier of the genus in which this occurrence is classified

genus gnl genus

The name of the genus in which this occurrence is classified

genus_no gnn genus

The identifier of the genus in which this occurrence is classified

cc cc2 loc

The country in which the collection is located, encoded as ISO-3166-1 alpha-2

state sta loc

The state or province in which the collection is located, if known

county cny loc

The county or municipal area in which the collection is located, if known

geogscale gsc loc

The geographic scale of the collection.

paleomodel pm1 paleoloc

The primary model specified by the parameter pgm. This field will only be included if more than one model is indicated.

paleolng pln paleoloc

The paleolongitude of the collection, evaluated according to the primary model indicated by the parameter pgm.

paleolat pla paleoloc

The paleolatitude of the collection, evaluated according to the primary model indicated by the parameter pgm.

geoplate gpl paleoloc

The identifier of the geological plate on which the collection lies, evaluated according to the primary model indicated by the parameter pgm. This might be either a number or a string.

paleomodel2 pm2 paleoloc

An alternate model specified by the parameter pgm. This field will only be included if more than one model is indicated. There may also be paleomodel3, etc.

paleolng2 pn2 paleoloc

An alternate paleolongitude for the collection, if the pgm parameter indicates more than one model. There may also be paleolng3, etc.

paleolat2 pa2 paleoloc

An alternate paleolatitude for the collection, if the pgm parameter indicates more than one model. There may also be paleolat3, etc.

geoplate2 gp2 paleoloc

An alternate geological plate identifier, if the pgm parameter indicates more than one model. There may also be geoplate3, etc.

cc cc2 prot

The country in which the collection is located, encoded as ISO-3166-1 alpha-2

protected ptd prot

The protected status of the land on which the collection is located, if any

early_age eag time

The early bound of the geologic time range associated with the collection or cluster (in Ma)

late_age lag time

The late bound of the geologic time range associated with the collection or cluster (in Ma)

cx_int_no cxi time

The identifier of the most specific single interval from the selected timescale that covers the entire time range associated with the collection or cluster.

early_int_no ein time

The beginning of a range of intervals from the selected timescale that most closely brackets the time range associated with the collection or cluster (with late_int_no)

late_int_no lin time

The end of a range of intervals from the selected timescale that most closely brackets the time range associated with the collection or cluster (with early_int_no)

formation sfm strat

The stratigraphic formation in which the collection is located, if known

stratgroup sgr strat

The stratigraphic group in which the collection is located, if known

member smb strat

The stratigraphic member in which the collection is located, if known

stratscale ssc stratext

The stratigraphic range covered by this collection

zone szn stratext

The stratigraphic zone in which the collection is located, if known

localsection sls stratext

The local section in which the collection is located, if known

localbed slb stratext

The local bed in which the collection is located, if known

localorder slo stratext

The order in which local beds were described, if known

regionalsection srs stratext

The regional section in which the collection is located, if known

regionalbed srb stratext

The regional bed in which the collection is located, if known

regionalorder sro stratext

The order in which regional beds were described, if known

stratcomments scm stratext

Additional comments about the stratigraphic context of the collection, if any

lithdescript ldc lith

Detailed description of the collection site in terms of lithology

lithology1 lt1 lith

The first lithology described for the collection site; the database can represent up to two different lithologies per collection

lithadj1 la1 lithext

Adjective(s) describing the first lithology

lithification1 lf1 lith

Lithification state of the first lithology described for the site

minor_lithology1 lm1 lith

Minor lithology associated with the first lithology described for the site

fossilsfrom1 ff1 lithext

Whether or not fossils were taken from the first described lithology

lithology2 lt2 lith

The second lithology described for the collection site, if any

lithadj2 la2 lithext

Adjective(s) describing the second lithology, if any

lithification2 lf2 lith

Lithification state of the second lithology described for the site. See above for values.

minor_lithology2 lm2 lith

Minor lithology associated with the second lithology described for the site, if any

fossilsfrom2 ff2 lithext

Whether or not fossils were taken from the second described lithology

abund_value abv abund

The abundance of this occurrence within its containing collection

abund_unit abu abund

The unit in which this abundance is expressed

environment env geo

The paleoenvironment of the collection site

tectonic_setting tec geo

The tectonic setting of the collection site

geology_comments gcm geo

General comments about the geology of the collection site

collection_aka crm rem

Any additional remarks that were entered about the collection

primary_reference ref 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.

FormatSuffixDocumentation
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.

VocabularyNameDefault forDescription
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