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) |