PBDB Data Service 1.1 v5

This is the stable version of the data service, and should be used for production applications. Any future changes to this version will be bug fixes only; new features and capabilities will be added to version 1.2.

DESCRIPTION

The function of this data service is to provide programmatic access to the information stored in the Paleobiology Database. Our goal is to make the entire database accessible by means of this service, so that anyone can write client software that interacts with it.

SCOPE

This service currently provides access to the following classes of information, by means of the indicated URLs. The following links will take you to pages which document the individual URL paths, listing the parameters accepted and the data fields returned by each.

Fossil occurrences

A fossil occurence represents the occurrence of a particular organism at a particular location in time and space. Each occurrence is a member of a single fossil collection, and has a taxonomic identification which may be more or less specific.

Fossil collections

A fossil collection is somewhat loosely defined as a set of fossil occurrences that are co-located geographically and temporally. Each collection has a geographic location, stratigraphic context, and age estimate.

Taxonomic names

The taxonomic names stored in the database are arranged hierarchically. Our tree of life is quite complete down to the class level, and reasonably complete down to the suborder level. Below that, coverage varies. Many parts of the tree have been completely entered, while others are sparser.

Geological time intervals and time scales

The database lists almost every geologic time interval in current use, including the standard set established by the International Commission on Stratigraphy (v2013-1).

Geological strata

Every fossil collection in the database is categorized by the formation from which it was collected, and many by group and member.

Bibliographic references

Each fossil occurrence, fossil collection and taxonomic name in the database is associated with one or more bibliographic references, identifying the source from which this information was entered.

Client configuration

This class provides information about the structure, encoding and organization of the information in the database. It is designed to enable the easy configuration of client applications.

For now, this service provides read-only access to the publicly available parts of the data. In the future, we plan to add an authentication module which will accept login credentials and will allow access to protected data, addition of new data, and modification of existing data.

USAGE

You can access this service by making HTTP requests whose URLs conform to a simple scheme. In most cases each URL maps to a single database query, and the body of the response represents some or all of the resulting records. For a description of how this information is encoded, see the documentation for the various output formats.

For example, consider the following URL:

/data1.1/taxa/single.json?name=Dascillidae&show=attr

An HTTP GET request using this URL would return information about the taxon Dascillidae (soft-bodied plant beetles). The components of this URL are as follows:

/data1.1/taxa/single

The URL path indicates the operation to be carried out. For a GET request, it specifies the class of information to be retrieved.

json

The path suffix indicates the format in which the results will be returned. In this case, the result will be expressed in Javascript Object Notation.

name=Dascillidae

Some of the parameters are used to construct a database query that will retrieve the desired information. This one selects a particular taxonomic name.

show=attr

Other parameters change or augment the set of information returned. This one specifies that in addition to basic information about the taxonomic name the result should also include the name's attribution.

Each URL path accepts its own set of parameters as well as a set of special parameters that control the form of the result.

For now, the only HTTP requests that are accepted are GET requests. Once we allow authentication and data modification, these operations will be carried out by means of POST, PUT and DELETE requests.

FORMATS

The following response formats are available for this data service. Not all of these may be available for every operation. You must select the desired format for a request by adding the appropriate suffix to the URI path.

FormatSuffixDocumentationDescription
JSON.jsonJSON format

The JSON format is intended primarily to support client applications, including the PBDB Navigator. Response fields are named using compact 3-character field names.

Comma-separated text.txtText formats

The text formats (txt, tsv, csv) are intended primarily for researchers downloading data from the database. These downloads can easily be loaded into spreadsheets or other analysis tools. The field names are taken from the PBDB Classic interface, for compatibility with existing tools and analytical procedures.

Comma-separated text.csvText formats

The text formats (txt, tsv, csv) are intended primarily for researchers downloading data from the database. These downloads can easily be loaded into spreadsheets or other analysis tools. The field names are taken from the PBDB Classic interface, for compatibility with existing tools and analytical procedures.

Tab-separated text.tsvText formats

The text formats (txt, tsv, csv) are intended primarily for researchers downloading data from the database. These downloads can easily be loaded into spreadsheets or other analysis tools. The field names are taken from the PBDB Classic interface, for compatibility with existing tools and analytical procedures.

RIS.risRIS format

The RIS format is a common format for bibliographic references.

PNG.pngPNG format

The PNG suffix is used with a few URL paths to fetch images stored in the database.

If an error occurs, the response body will be a JSON object if the URL path suffix is json and HTML otherwise. If the URL path suffix is not recognized, an error of type 415 Unknown Media Type will be returned.

VOCABULARIES

The following response vocabularies are available for this data service. 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 namespbdbtxt, 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 namescomjson

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