Skip to content

Samples Endpoint

NEON samples are physical objects collected or measured and tracked over time. Most samples are collected and archived for later analysis by researchers. Some samples remain in the field, such as trees and live mammals, while others are discarded after analysis, such as surface water samples. A sample hierarchy is created when a sample is subsampled, or when multiple samples are pooled, creating child samples. Any sample may have parent samples or child samples.

Sample information is managed internally by NEON's Sample Management System (SMS). The samples endpoint provides read access into the SMS.

The samples endpoint, just like the Sample Viewer user interface that is built from it, has two primary purposes:

  1. to find the current or past physical location of a sample
  2. to explore the sample hierarchy

Samples are organized by classes of sample type. The sample class name, or key, is a string that starts with the name of the data ingest table that NEON uses following a sampling or laboratory protocol, followed by a period and the ID name. For example, "bet_IDandpinning_in.individualID" is a sample class for individual Carabids that are identified and pinned. Use the /samples/supportedClasses endpoint to download the current list of supported sample classes.

Use the /samples/view endpoint to request information about sample custody events for a sample, as well as any parent or child samples, using a specified sample ID. Generally, sample IDs are found in downloaded data products. Sample IDs may be a combination of sampleTag and sampleClass, a unique sampleUuid (an identifier unique within NEON), a barcode, or an archiveGuid (a globally unique identifier generated by an archive facility).

Some sampleTags are unique within a sample class, but are duplicated in other sample classes. Use the /samples/classes endpoint when you know a sampleTag but not sampleClass - the response from this endpoint will return one or more options.

Finally, use the /samples/download endpoint to obtain a limited set of data for a unique sample ID and a specified number of degrees of relatedness (for example, N=2 returns any immediate parent or child sample data, while N=3 will return any data from samples related by three degrees).

If you are interested in requesting an archived sample for your research, the data returned can tell you if a given sample was archived, and at what facility. Visit the Biorepository Portal to request samples. If your primary interest is in data for analysis, use the NEON data portal.

Paths

GET /samples/classes

Description

Get a list of Sample Classes for a given Sample Tag

Parameters

Type Name Description Schema
Query sampleTag
required
Sample Tag of interest string

Responses

HTTP Code Description Schema
200 List of sample classes for a given Sample Tag Response 200
400 Bad Request error
404 Sample Not Found error
default General error error
Response 200
Name Schema
data classes

Produces

  • application/json

Tags

  • Samples

GET /samples/download

Description

Get a list of sample views for a given sample identifier and search degree.

Parameters

Type Name Description Schema
Query sampleTag Sample Tag of interest. Must be used in conjunction with a Sample Class. string
Query sampleClass Sample Class of interest. Must be used in conjunction with a Sample Tag. string
Query barcode Barcode of Sample. Must be used on its own. string
Query sampleUuid UUID of Sample. Must be used on its own. string
Query archiveGuid archiveGuid of Sample. Must be used on its own. string
Query degree Degree of sample search within a sample hierarchy string

Responses

HTTP Code Description Schema
200 List of sample views Response 200
400 Bad Request error
404 Sample Not Found error
default General error error
Response 200
Name Schema
data views

Produces

  • application/json

Tags

  • Samples

GET /samples/supportedClasses

Description

Get a list of sample classes and descriptions currently available

Responses

HTTP Code Description Schema
200 List of supported sample classes and their descriptions Response 200
default General error error
Response 200
Name Schema
data supportedClasses

Produces

  • application/json

Tags

  • Samples

GET /samples/view

Description

For a given sample identifier, get a list of sample custody events as well as any parent and child sample identifiers that currently exist.

Parameters

Type Name Description Schema
Query sampleTag
optional
Sample Tag of interest. Must be used in conjunction with a Sample Class. string
Query sampleClass
optional
Sample Class of interest. Must be used in conjunction with a Sample Tag. string
Query barcode
optional
Barcode of Sample. Must be used on its own. string
Query sampleUuid
optional
UUID of Sample. Must be used on its own. string
Query archiveGuid
optional
archiveGuid of Sample. Must be used on its own. string

Responses

HTTP Code Description Schema
200 List of sample views Response 200
400 Bad Request error
404 Sample Not Found error
default General error error
Response 200
Name Schema
data views

Produces

  • application/json

Tags

  • Samples

Definitions

classes

Name Description Schema
sampleClasses Array of Sample Classes for a given sample [string]

entry

Name Description Schema
key Sample Class Name string
value Sample Class Description string

sampleEvent

Sample Event for a given sample

Name Description Schema
ingestTableName Ingest Table Name string
smsFieldEntries [smsField]

sampleInfo

Name Description Schema
sampleUuid UUID for a given sample string
sampleTag Sample Tag for a given sample string
sampleClass Sample Class for a given sample string
barcode Sample Barcode for a given sample string
archiveGuid Archive GUID for a given sample string

sampleView

Name Description Schema
sampleUuid UUID for a given sample string
sampleTag Sample Tag for a given sample string
sampleClass Sample Class for a given sample string
barcode Sample Barcode for a given sample string
archiveGuid Archive GUID for a given sample string
sampleEvents [sampleEvent]
parentSampleIdentifiers [sampleInfo]
childSampleIdentifiers [sampleInfo]

smsField

Name Description Schema
smsKey SMS Field Name string
smsValue SMS Field Value string

supportedClasses

Name Description Schema
entries Array of Sample Classes and their descriptions for a given sample [entry]

views

Name Description Schema
sampleViews Array of sample views for a given sample [sampleView]

error

Name Schema
detail
optional
string
status
optional
number (int)