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:
- to find the current or past physical location of a sample
- 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) |