NEON Data API

 

The NEON API (Application Programming Interface) can be used to quickly access NEON data and information about our data products and sampling locations. This API provides a simple means of constructing URLs or CURL statements that return information in a common machine-readable format, JSON (JavaScript Object Notation).

 

The API provides numerous endpoints, each delivering different types of data or information. Some endpoints provide the option to enter values for specific parameters that allow you to refine your search. Click on the interactive table below to discover and try out the various endpoints. Below the table, read more details about each endpoint. If you need more information, try visiting our FAQ, GitHub repository, or Using the NEON API tutorial. We also provide an R package that you can use to download and reformat the data.    

 

Tell us what you think: If you have design ideas, functionality requests, bug notes, examples of how you used the API, or anything else you would like us to know, please file an issue and tell us about it! This API will be enhanced as we receive feedback from the community.

 

Swagger UI

Endpoint Notes

Products

The /products endpoint provides information about NEON data products, including availability by site and month (also see the data product catalog). In the API, data products are specified using a 13 character code. For instance, Chemical properties of groundwater uses product code DP1.20092.001, where DP1 refers to data level 1 (quality controlled), 20092 is the unique numeric id of the data product, and 001 refers to the revision. All of our data products are currently provisional and annotated as revision 1.

Sites

The /sites endpoint provides information about NEON field sites where data are currently available.  Numerous data products are produced from each site. Site names are abbreviated into four-letter site codes -- for example, the Arikaree River site abbreviation is ARIK. For more information about sites, you can find a listing on our main website. If you need to know about our remote sensing data availability, visit the Airborne Data webpage.

Locations

The /locations endpoint provides more detailed information about where NEON collects data than the /sites endpoint. A location is any discrete place or administrative region in the NEON system, ranging from our huge ecoregions (domains) to single data collection points. Location information may consist of geographic coordinates (latitude, longitude, elevation, etc.), plot size, and other positional information. There are more than 150,000 locations in the NEON system. REALM is the top of the location hierarchy, and contains all of the domain names as "locationChildren". Each domain, in turn, contains all of its site codes. Each site contains towers, measurement plots, observation spots, and more. By traversing this hierarchy of locations, information about any point in the NEON system is available.

An example of this hierarchy is as follows: REALM contains 20 Domains, one of which is Domain 14 (Desert Southwest). D14 has three sites, one of which is the Santa Rita Experimental Range site (SRER). SRER has a single meteorology tower named TOWER104454 with numerous sensors, each at a named location. SRER also has nine mammal trapping grids, one of which is SRER_002.mammalGrid.mam. Each grid has numerous trapping locations. Examples of individual locations include Domain 02, or the Central Plains Experimental Range, Plot 11, mammal collection point A10, or Niwot Ridge Mountain Research Station Megapit MP1. Note that location names are case-sensitive.

The /locations/sites endpoint takes no arguments, and provides a list of all sites and their location information.

The /locations/{locationName} endpoint can be used to deliver location information for any given named location ID. Some named locations may be moved over the course of the Observatory. Optional parameters for this endpoint include whether or not the response should contain the location's history or position within a broader hierarchy. The locationType parameter may be populated with one of many values, including TOWER, HUT, MEGAPIT, and others. A full list of available locationTypes will be made available soon.

Data

The /data endpoint shows which monthly data files are available, and provides URLs to downloadable files. Several terabytes of data are presently available. To keep data files to a reasonable size, they are generally arranged in product/site/monthly chunks. Even so, files can be large and you may find it worthwhile to check the size attribute before downloading. Also note that the provided URLs are from an Amazon S3 service and expire about 24 hours after generation. If the time between when you obtain a URL and start downloading the file is more than 24 hours, you may need to obtain a new URL before proceeding.

Taxonomy

The /taxonomy endpoint provides acess to NEON's taxon lists for major groupings such as plants, algae, beetles, and small mammals. Taxon lists are compiled from a variety of published sources, and are primarily used by field staff to constrain data entry to verified scientific names and known geographic ranges. For more information, visit the Taxonomic Lists webpage. Note that the offset and limit parameters currently have default values of 50; you may wish to use an offset value of 0 and adjust the limit value to support larger recordsets. Also note that the scientificname parameter only supports exact, not fuzzy, string matching.

Samples

NEON samples are physical objects collected or measured and tracked over time. Most samples are collected and held in possession, but some samples remain in the field, such as trees and live mammals. Some samples are discarded after analysis, such as surface water samples, and some samples may be archived, such as beetles. A sample hierarchy is created when a sample is subsampled, or when multiple samples are pooled, creating child sample(s). Any sample may have parent sample(s) and/or child sample(s).

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

Currently, all samples are supported except for those associated with ground beetles and canopy foliage; future updates will add the remaining samples. 

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 either a combination of sampleTag and sampleClass, or a unique sampleUuid (a NEON-generated identifier unique within NEON), barcode, or archiveGuid (a globally unique identifier generated by an archive facility).

Some of the sampleTags that were generated early during NEON construction are unique within a sample class, but may have been reused by 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. If your primary interest is in data for analysis, use the NEON data portal.

NEON Data Usage and Citation Policy