Neotoma Developer Center

Remote programmatic access to the Neotoma Database

User Tools

Site Tools


Datasets

Resource URI:

api.neotomadb.org/v1/data/datasets

Description

Returns a collection of dataset metadata objects.

A dataset is a set of samples for a particular data type from a Collection Unit. A Collection Unit may have multiple datasets for different data types, for example a dataset for pollen and another for plant macrofossils.

Request Parameters

Any of the following parameters may be specified in the call. If no parameters are provided, all datasets in the database will be returned. Alternatively, use parameters to filter results to a subset of datasets.

It is common to search for datasets by associated site properties such as geographic coordinates, geopolitical name, and altitude. Therefore, for convenience, several site search parameters are supported on the datasets resource.

Parameter Description
siteid Unique database record identifier for a site.
datasettype The dataset type; see below.
piid ContactID of a principal investigator associated with the dataset.
altmin Minimum site altitude in meters.
altmax Maximum site altitude in meters.
loc Geographic bounding box within which to constrain the search. Coordinates are specified in decimal degrees as a comma-separated list in the following order: longitudeWest, latitudeSouth, longitudeEast, latitudeNorth.
gpid Geopolitical entity id in which the datasets occur; see below.
taxonids Unique database record identifier for a taxon; accepts one or more ids separated by commas.
taxonname Name or partial name of the taxon/taxa.
ageold Oldest age, as calendar years before present, to include in results.
ageyoung Youngest age, as calendar years before present, to include in results.
ageof Indicates to which elements of a dataset search ages should apply; see below.
subdate Return datasets submitted on or after a specified date. Format dates as YYYY-MM-DD or MM-DD-YYYY.

Dataset Type

Accepted values are:

  • geochronologic
  • loss-on-ignition
  • pollen
  • plant macrofossils
  • vertebrate fauna
  • mollusks
  • pollen surface sample

Geopolitical Units

Accepted values are those in the GeoPoliticalID column in the following table: GeoPoliticalUnits.

Dataset, Sample, or Taxon Ages

Dataset searches may be limited by age range criteria as described below.

Accepted values for ageof parameter:

Value Description
sample Default; apply ages specified to the age of individual samples within a dataset.
taxon Apply ages specified to the age of the taxon specified.
dataset Apply ages specified to the age bounds of the entire dataset.

When making a request that includes taxonid or taxonname along with age parameters, the ageof value must be set to “taxon” or an error will occur.

You may specify both, one, or none of the age parameters to construct search types like those below.

Specified Ages Result
both Dataset/sample/taxon whose age/age range is contained within the range ageold–ageyoung.
only ageold Dataset/sample/taxon whose age/age range is contained within the range ageold–present.
only ageyoung Dataset/sample/taxon whose age/age range is contained within the range 5.5 Ma–ageyoung; 5.5 Ma is approximate limit to Neotoma database.

Response Properties

A dataset resource is described by the following properties.

Property Description
DatasetID Unique database record identifier for the dataset.
DatasetName Name of the dataset; not commonly used.
ColUnitHandle Code name of the Collection Unit with which the dataset is associated. This code may be up to 10 characters. Data are frequently distributed by Collection Unit, and the Handle is used for file names.
CollectionUnitID Unique database record identifier for the collection unit.
ColUnitType The collection type. Types include cores, sections, excavations, and animal middens.
DatasetType The dataset type, such as: geochronologic, loss-on-ignition, pollen, plant macrofossils, vertebrate fauna, etc.
AgeOldest The oldest of all sample ages (in calendar years before present) in the dataset.
AgeYoungest The youngest of all sample ages (in calendar years before present) in the dataset.
SubDates An array of objects that describe dataset submission events; see below.
DatasetPIs An array of objects that describe Principal Investigators associated with a dataset; see below.
Site An object describing the site where the dataset samples were taken; see below.

Dataset Submissions

Submissions may be original submissions, resubmissions, compilations from other databases, or recompilations. See the Neotoma Database Manual for more information.

A dataset submission object is described by the following properties.

Property Description
SubmissionDate Date of the submission, resubmission, compilation, or recompilation
SubmissionType Description of submission event.

DatasetPI Object

A datasetPI object is described by the following properties.

Property Description
ContactID Unique database record identifier for the person.
ContactNameFull name of the person, last name first (e.g. “Simpson, George Gaylord”) or name of organization or project (e.g. “Great Plains Flora Association”).

Site Object

A site object is described by the following properties.

Property Description
SiteID Unique database record identifier for the site.
SiteName Name of the site.
Altitude Altitude in meters.
LatitudeNorth North bounding latitude, in decimal degrees, for a site.
LatitudeSouth South bounding latitude, in decimal degrees, for a site.
LongitudeEast East bounding longitude, in decimal degrees, for a site.
LongitudeWest West bounding longitude, in decimal degrees, for a site.
SiteDescription Free form description of a site, including such information as physiography and vegetation around the site.

Examples

Request Description
http://api.neotomadb.org/v1/data/datasets All datasets
http://api.neotomadb.org/v1/data/datasets?datasettype=pollen All pollen datasets
http://api.neotomadb.org/v1/data/datasets?siteid=1711 Datasets for site id 1711 (Moon Lake (SD,USA))
http://api.neotomadb.org/v1/data/datasets?taxonids=5868&ageold=9000&ageyoung=4500&ageof=taxon Datasets with dated Bison bison occurrences within the time range 9000-4500 years before present
http://api.neotomadb.org/v1/data/datasets?ageold=9000&ageyoung=4500&ageof=sampleDatasets that contain sample(s) dated 9000-4500 years before present
http://api.neotomadb.org/v1/data/datasets?ageold=130000&ageyoung=11800&ageof=dataset Datasets with age bounds within the Late Pleistocene
http://api.neotomadb.org/v1/data/datasets?piid=44&gpid=6456&datasettype=pollen Eric Grimm's (Contact ID = 44) pollen datasets in Florida, USA

View sample response

View sample response

View sample response

{
    "success":1,
    "data":[
        {
            "DatasetID":819,
            "DatasetName":null,
            "CollectionUnitID":796,
            "ColUnitHandle":"FAR",
            "Type":"pollen",
            "AgeOldest":4416,
            "AgeYoungest":0,
            "SubDate":"2007-06-30",
            "ColUnitType":"Core",
            "DatasetPIs":[
                {
                    "Order":1,
                    "ContactID":85,
                    "ContactName":"Richard, Pierre J. H."
                },
                {
                    "Order":2,
                    "ContactID":61,
                    "ContactName":"Larouche, Alayn C."
                }
            ],
            "Site":{
                "SiteID":797,
                "SiteName":"Lac Faribault",
                "Altitude":250,
                "LatitudeNorth":58.866944,
                "LatitudeSouth":58.866944,
                "LongitudeEast":-110.433333,
                "LongitudeWest":-110.433333
            }
        }
    ]
}

Page Tools