Skip to content

Locations Endpoint

The /locations endpoint provides more detailed information about where NEON collects data than the /sites endpoint. A "named location", truncated to "location" here, 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 one or more field sites. Each site contains towers, measurement plots, observation spots, and more. By traversing this hierarchy of locations, information about any data collection 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 field 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. 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.

Paths

GET /locations/sites

Description

Get information about the site-level locations.

Responses

HTTP Code Description Schema
200 List of locations Response 200
default General error error
Response 200
Name Schema
data [location]

Produces

  • application/json

Tags

  • Locations
  • Sites

GET /locations/{locationName}

Description

Get information about a location.

Parameters

Type Name Description Schema
Path locationName
required
Location to get string
Query hierarchy
optional
Option to obtain location hierarchy information boolean
Query history
optional
Option to obtain location history information boolean
Query locationType
optional
"When obtaining location hierarchy, specify a type of descendant to query for. For example, to obtain the location hierarchy for all towers at location CPER, utilize: /CPER?hierarchy=true&locationType=TOWER" string

Responses

HTTP Code Description Schema
200 Single location Response 200
400 Location(s) not found Response 400
default General error error
Response 200
Name Schema
data location
Response 200
Name Schema
errors
optional
[error]

Produces

  • application/json

Tags

  • Locations

Definitions

location

Name Description Schema
locationName
optional
Name of the location string
locationDescription
optional
A description of the location string
locationType
optional
Type of the location string
domainCode
optional
Three character domain abbreviation (D01, D02, etc) for the domain the location is in string
siteCode
optional
Four character code for a field site string
locationDecimalLatitude
optional
Decimal latitude for the location (WGS 84) number (double)
locationDecimalLongitude
optional
Decimal longitude for the location (WGS 84) number (double)
locationElevation
optional
Elevation for the location in meters number (double)
locationUtmEasting
optional
The Universal Transverse Mercator easting number (double)
locationUtmNorthing
optional
The Universal Transverse Mercator northing number (double)
locationUtmHemisphere
optional
The single character Universal Transverse Mercator hemisphere string
locationUtmZone
optional
The Universal Transverse Mercator zone number (int)
alphaOrientation
optional
The elevation or pitch angle (in degrees) in the vertical plane at which a sensor is oriented relative to the horizontal plane.
betaOrientation
optional
The roll angle (in degrees) about the longitudinal axis of the sensor at which the sensor is oriented. number (double)
gammaOrientation
optional
The azimuth or yaw angle (in degrees) at which a sensor is facing relative to true North. number (double)
xOffset
optional
Cartesian offsets of a sensor, in meters, west (positive values) or east (negative values) relative to the reference location. number (double)
yOffset
optional
CCartesian offsets of a sensor, in meters, south (positive values) or north (negative values) relative to the reference location. number (double)
zOffset
optional
Cartesian offsets of a sensor, in meters, up (positive values) or down (negative values) relative to the reference location. number (double)
offsetLocation
optional
The named location used as a reference point. Offsets are relative to this location. location
activePeriods
optional
List of active periods for the location [activePeriod]
locationPolygon
optional
locationPolygon
locationProperties
optional
List of properties associated with the location. Contents vary based on the type of location. [locationProperties]
locationHistory
optional
[locationHistory]
locationParent
optional
Name of the location that this location is in string
locationParentUrl
optional
URL to request location data for the parent of this location string
locationParentHierarchy
optional
When querying for the hierarchy, the location's parent hierarchy locationParentHierarchy
locationChildren
optional
A list of names of locations within this location [string]
locationChildrenUrls
optional
A list of URLs to request location data for the children of this location [string]
locationChildHierarchy
optional
When querying for the hierarchy, the location's set of immediate children and associated hierarchy [locationChildHierarchy]

activePeriod

Name Description Schema
activatedDate
optional
The activation date for the time period string
deactivatedDate
optional
The deactivation date for the time period string

locationPolygon

Name Description Schema
coordinates
optional
A list of vertices that define the closed structure for the polygon [coordinates]

coordinates

Name Description Schema
latitude
optional
Decimal latitude for the polygon coordinate number (double)
longitude
optional
Decimal longitude for the polygon coordinate number (double)
elevation
optional
Elevation for the polygon coordinate number (double)

locationProperties

Name Description Schema
locationPropertyName
optional
An additional property for the location, described by its name string
locationPropertyValue
optional
The value of the additional property; can be a string or a number string

locationHistory

Name Description Schema
current Indicates if this is the current set of coordinates or spatial position for this location name boolean
locationStartDate The start date and time for this location string (date-time)
locationEndDate
optional
The end date and time for this location string (date-time)
locationDecimalLatitude
optional
Decimal latitude for the location number (double)
locationDecimalLongitude
optional
Decimal longitude for the location number (double)
locationElevation
optional
Elevation for the location number (double)
locationUtmEasting
optional
The Universal Transverse Mercator easting number (double)
locationUtmNorthing
optional
The Universal Transverse Mercator northing number (double)
locationUtmHemisphere
optional
The single character Universal Transverse Mercator hemisphere string
locationUtmZone
optional
The integer Universal Transverse Mercator zone number (int)
alphaOrientation
optional
The elevation or pitch angle (in degrees) in the vertical plane at which a sensor is oriented relative to the horizontal plane.
betaOrientation
optional
The roll angle (in degrees) about the longitudinal axis of the sensor at which the sensor is oriented. number (double)
gammaOrientation
optional
The azimuth or yaw angle (in degrees) at which a sensor is facing relative to true North. number (double)
xOffset
optional
Cartesian offsets of a sensor, in meters, west (positive values) or east (negative values) relative to the reference location. number (double)
yOffset
optional
CCartesian offsets of a sensor, in meters, south (positive values) or north (negative values) relative to the reference location. number (double)
zOffset
optional
Cartesian offsets of a sensor, in meters, up (positive values) or down (negative values) relative to the reference location. number (double)
locationPolygon
optional
locationPolygon
locationProperties
optional
List of properties associated with the location. Contents vary based on the type of location. [locationProperties]

locationParentHierarchy

Name Description Schema
locationName
optional
Name of the location string
locationType
optional
Type of the location string
locationParent
optional
Name of the location that this location is in string
locationParentHierarchy
optional
The location's parent hierarchy object
locationParentUrl
optional
URL to request location data for the parent of this location string

locationChildHierarchy

Name Description Schema
locationChildHierarchy
optional
The location's child hierarchy [object]
locationDescription
optional
A description of the location string
locationName
optional
Name of the location string
locationType
optional
Type of the location string

error

Name Schema
detail
optional
string
status
optional
number (int)