GraphQL API¶

In addition to providing REST API endpoints, the NEON Data API also provides a GraphQL endpoint, allowing users to take advantage of the flexibility and efficiency of the GraphQL data query language to access NEON metadata and data.

The /graphql endpoint affords users the ability to define precisely the desired data in the request and receive only the desired data in response.

Using GraphQL¶

The following example will illustrate how to use the GraphQL endpoint by comparing a /products endpoint request for the current REST API to a comparable GraphQL query.

REST API¶

In order to retrieve all data product codes, names, and descriptions with the REST /products endpoint, the following request would need to be made to obtain all associated metadata for a data product.

Example

Request:

cURLHTTPie

curl -X GET https://data.neonscience.org/api/v0/products >> neon-data-products.json

http --download --output=neon-data-products.json GET https://data.neonscience.org/api/v0/products

Response:
Showing the first element in the products array, properties truncated and excluded for brevity.

{
  "data": [
    {
      "productCodeLong": "...",
      "productCode": "...",
      "productCodePresentation": "...",
      "productName": "...",
      "productDescription": "...",
      ...
      "themes": [...],
      "changeLogs": [...],
      "specs": [...],
      "keywords": [...],
      "siteCodes": [...]
    }
    ...
  ]
}

GraphQL Query¶

If a user wants to retrieve all product codes, names, and descriptions, with the /graphql endpoint, given the following GraphQL schema object:

# GraphQL Schema Language Definition
type DataProduct {
  productCode: String
  productName: String
  productDescription: String
  productScienceTeam: String
  productPublicationFormatType: String
  productAbstract: String
  productHasExpanded: Boolean
  productBasicDescription: String
  productExpandedDescription: String
  themes: [String!]
  keywords: [String!]
  specs: [DataProductSpec!]
  siteCodes: [DataProductSite!]
}

The shape of the GraphQL schema definition will determine how queries can be formed. Note that in the following query, the DataProduct object designates three properties that are defined in the schema definition. A POST request with the following JSON body would produce the desired result:

{
  "query": "query Products {
    products {
      productCode
      productName
      productDescription
    }
  }"
}

Example

Request:

cURLHTTPie

curl -H "Content-Type: application/json" -X POST -d " \
{ \
  \"query\": \"query Products { \
    products { \
      productCode \
      productName \
      productDescription \
    } \
  }\" \
} \
" https://data.neonscience.org/graphql >> neon-data-products-graphql.json

http --download --output=neon-data-products-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Products { \
    products { \
      productCode \
      productName \
      productDescription \
    } \
  }"

As the shape of the request query determines the shape of the response, each product element in the array would have the following properties:

{
  "productCode": "...",
  "productName": "...",
  "productDescription": "..."
}

Response:
Showing the first element in the products array, property values truncated for brevity.

{
  "data": {
    "products": [
      {
        "productCode": "...",
        "productName": "...",
        "productDescription": "...",
      }
      ...
    ]
  }
}

Note

GraphQL queries can also describe the name of the response property by setting an alias for the query. For example, the products array in the GraphQL response will be a property on the root data object. The name of the property on the data object reflects the name of the alias given to the query in the request.

Default AliasNamed Alias

# Query
{
  "query": "query Products {
    products {
      productCode
      productName
      productDescription
    }
  }"
}

# Response
{
  "data": {
    "products": [
      {
        "productCode": "...",
        "productName": "...",
        "productDescription": "...",
      }
      ...
    ]
  }
}

# Query
{
  "query": "query Products {
    productList: products {
      productCode
      productName
      productDescription
    }
  }"
}

# Response
{
  "data": {
    "productList": [
      {
        "productCode": "...",
        "productName": "...",
        "productDescription": "...",
      }
      ...
    ]
  }
}

To see this query in action, try it out using the GraphQL Explorer!
Copy the following GraphiQL query into the query editor window and perform the request.

query Products {
  products {
    productCode
    productName
    productDescription
  }
}

See the Examples section for more query examples.

Endpoint Definition¶

POST `/graphql`¶

Description¶

All GraphQL queries utilize a single /graphql endpoint.

Queries¶

Supported queries for the GraphQL endpoint.

Field	Arguments	Response Type	Description
products	release String	[DataProduct!]	Get all data products
product	productCode String! release String	DataProduct!	Get a single product by product code with optional set of site codes to include in the associated sites collection
filterProducts	filter DataProductFilter!	[DataProduct!]	Get a set of data products based on a data product filter
sites	release String	[Site!]	Get all sites
site	siteCode String! release String	Site!	Get a single site by site code
filterSites	filter SiteFilter!	[Site!]	Get a set of sites based on a site filter
location	name String!	Location!	Get a single location by name
locationHierarchy	name String! locationType String	Location!	Get a single location hierarchy by name and optional type. Specify a type of descendant to query for. For example, to obtain the location hierarchy for all towers at location CPER, utilize: locationType=TOWER
findLocations	query LocationQuery!	[Location!]	Get a set of locations based on a location query. The maximum allowable number of locations for a single request is 1000.
prototypeDatasets		[PrototypeDataset!]	Get all prototype datasets
prototypeDataset	uuid String!	PrototypeDataset!	Get a prototype dataset based on UUID

Objects¶

ActivePeriod¶

Type definition for an active period for a location

Field	Argument	Type	Description
activatedDate		DateTime	The activation date for the time period
deactivatedDate		DateTime	The deactivation date for the time period

AvailableRelease¶

Type definition for associating a release with the set of months that have available data within the containing product or site

Field	Argument	Type	Description
release		String	The release that this availability refers to
availableMonths		[String]	List of years and months that products are available. Formatted as YYYY-MM.

Coordinate¶

Type definition for a coordinate

Field	Type	Description
latitude	Float	Decimal latitude for the coordinate
longitude	Float	Decimal longitude for the coordinate
elevation	Float	Elevation for the coordinate

DataProduct¶

Type definition for a data product

Field	Type	Description
productCode	String	Revisioned, shortened code for the data product (DP1.00001.001, DP1.10072.001, etc)
productName	String	The name of the data product
productDescription	String	A brief description of the data product
productStatus	String	Future, active, or retired product status
productScienceTeam	String	Science team responsible for the data product
productPublicationFormatType	String	Class of publication system used during the publication process; can be independent from productScienceTeam.
productAbstract	String	An abstract of the data product
productHasExpanded	Boolean	Whether a data product has expanded data
productBasicDescription	String	A description of the basic package available for download
productExpandedDescription	String	A description of the expanded package available for download
themes	[String]	List of themes to which the data product belongs.
keywords	[String]	List of words and phrases associated with the data product
specs	[DataProductSpec]	List of documents associated with the data product.
releases	[DataProductRelease]	List of releases associated with the data product.
siteCodes	[DataProductSite]	List of sites and months of available data

DataProductDoi¶

Type definition for a set of DOIs associated with a data product and release

Field	Argument	Type	Description
url		String	The URL of the DOI
generationDate		DateTime	The generation date of the DOI

DataProductRelease¶

Type definition for a release associated with a data product.

Field	Type	Description
release	String	The name of the release
generationDate	DateTime	The generation date of the release
url	String	The URL of the release API endpoint
productDoi	DataProductDoi	The DOI definition for the product and release

DataProductSite¶

Type definition for a set of sites describing available data associated with a data product

Field	Type	Description
siteCode	String	Four character code for the site
availableMonths	[String]	List of years and months that products are available. Formatted as YYYY-MM.
availableDataUrls	[String]	List of data urls for products that are available.
availableReleases	[AvailableRelease]	List of available releases and associated months that have available data within the containing product, site combination.

DataProductSpec¶

Type definition for a set of documents associated with a data product

Field	Type	Description
specId	String	Document identifier for the associated document
specNumber	String	Document code for the associated document
specType	String	The MIME type associated with the document.
specSize	String	The size in bytes of the document.
specDescription	String	The description of the document.

Location¶

Type definition for a NEON location

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

LocationChildHierarhcy¶

Type definition for a child location hierarchy

Field	Type	Description
locationName	String	Name of the location
locationType	String	Type of location
locationDescription	String	A description for the location
locationChildHierarchy	[LocationChildHierarhcy!]	The location's child hierarchy

LocationHistory¶

Type definition for a history record for a location

Field	Type	Description
current	Boolean	Indicates if this is the current location for this location
locationStartDate	DateTime	The start date and time for this location
locationEndDate	DateTime	The end date and time for this location
locationDecimalLatitude	Float	Decimal latitude for the location
locationDecimalLongitude	Float	Decimal longitude for the location
locationElevation	Float	Elevation for the location
locationUtmEasting	Float	The Universal Transverse Mercator easting
locationUtmNorthing	Float	The Universal Transverse Mercator northing
locationUtmHemisphere	String	The single character Universal Transverse Mercator hemisphere
locationUtmZone	Int	The integer Universal Transverse Mercator zone
alphaOrientation	Float	The elevation or pitch angle (in degrees) in the vertical plane at which a sensor is oriented relative to the horizontal plane.
betaOrientation	Float	The roll angle (in degrees) about the longitudinal axis of the sensor at which the sensor is oriented.
gammaOrientation	Float	The azimuth or yaw angle (in degrees) at which a sensor is facing relative to true North.
xOffset	Float	Cartesian offsets of a sensor, in meters, west (positive values) or east (negative values) relative to the reference location.
yOffset	Float	Cartesian offsets of a sensor, in meters, south (positive values) or north (negative values) relative to the reference location.
zOffset	Float	Cartesian offsets of a sensor, in meters, up (positive values) or down (negative values) relative to the reference location.
locationPolygon	Polygon	A list of vertices that define the closed structure for the polygon
locationProperties	[LocationProperty!]	List of properties associated with the location. Contents vary based on the type of location

LocationParentHierarchy¶

Type definition for a parent location hierarchy

Field	Type	Description
locationName	String	Name of the location
locationType	String	Type of location
locationParent	String	Name of the location that this location is in
locationParentUrl	String	RL to request location data for the parent of this location
locationParentHierarchy	LocationParentHierarchy	The location's parent hierarchy

LocationProperty¶

Type definition for a generic location property value

Field	Argument	Type	Description
locationPropertyName		String	The name of the property
locationPropertyValue		AnyScalar	The value of the property

Polygon¶

Type definition for a polygon

Field	Argument	Type	Description
coordinates		[Coordinate!]!

PrototypeData¶

Type definition for prototype dataset data

Field	Type	Description
url	String	The data URL for accessing the data files for the dataset
files	[PrototypeDataFile!]	List of data files for the dataset
dataLocations	[PrototypeDataLocation!]	List of data locations for the dataset

PrototypeDataFile¶

Type definition for prototype dataset data file

Field	Type	Description
name	String	The name of the data file
description	String	A description of the data file
fileSize	Int	File size in bytes
fileName	String	Filename
md5	String	MD5 checksum value in hex
type	PrototypeDataFileType!	The type of the data file (metadata, data, etc)
url	String	Download URL

PrototypeDataFileType¶

Type definition for prototype dataset data file type

Field	Argument	Type	Description
name		String	The name of the data file type
description		String	The description of the data file type

PrototypeDataLocation¶

Type definition for a prototype dataset data location

Field	Type	Description
path	String	The path or URL to the data location
description	String	A description of the data location referenced by the path
metadata	Boolean	Indicates that this data location refers to metadata exclusively

PrototypeDataset¶

Type definition for a prototype dataset

Field	Type	Description
uuid	String	The UUID of the dataset
projectTitle	String	The title of the project
projectDescription	String	The description of the project
designDescription	String	A description of the dataset's design
metadataDescription	String	A brief description of the metadata associated with the dataset
studyAreaDescription	String	A description of the dataset's spatial extent
datasetAbstract	String	An abstract of the dataset
startYear	Int	The start year for the time span of the dataset
endYear	Int	The end year for the time span of the dataset
dateUploaded	DateTime	The date the dataset was uploaded
isPublished	Boolean	Whether or not the dataset has been included in a publication
version	String	The version of the dataset
versionDescription	String	The version description
doi	PrototypeDatasetDoi	The DOI for the dataset
relatedVersions	[PrototypeDatasetRelatedVersion!]	The related versions of this dataset
data	PrototypeData	The dataset's data files
dataThemes	[String!]	List of themes to which the dataset belongs
fileTypes	[PrototypeFileType!]	List of file types to which the dataset belongs
keywords	[String!]	List of words and phrases associated with the dataset
locations	[PrototypeLocation!]	List of locations of the dataset's spatial extent
publicationCitations	[PrototypePublicationCitation!]	List of publication citations involving the dataset
relatedDataProducts	[PrototypeRelatedDataProduct!]	List of data product's that the dataset is related to
scienceTeams	[String!]	List of responsible science teams for the dataset

PrototypeDatasetDoi¶

Type definition for a Prototype Dataset related version

Field	Argument	Type	Description
url		String	The URL of the DOI
generationDate		DateTime	The generation date of the DOI

PrototypeDatasetRelatedVersion¶

Type definition for a Prototype Dataset related version

Field	Type	Description
datasetUuid	String	The related dataset UUID
datasetProjectTitle	String	The related dataset project title
datasetVersion	String	The related dataset version

PrototypeFileType¶

Type definition for a prototype dataset file type

Field	Argument	Type	Description
name		String	The name of the file type (CSV, PDF, HDF5, etc)
description		String	A description of the file type

PrototypeLocation¶

Type definition for a prototype dataset location

Field	Type	Description
domain	String	Three character domain abbreviation (D01, D02, etc) for the domain this site is in
state	String	Two letter state code that this site is in
siteCode	String	Four character code for the site
siteName	String	Full name for the site
latitude	Float	Decimal latitude for the location
longitude	Float	Decimal longitude for the location

PrototypePublicationCitation¶

Type definition for a prototype dataset publication citation

Field	Type	Description
citation	String	The citation associated with a publication involving the dataset
citationIdentifier	String	The citation identifier (DOI, arXiv, URL) associated with a publication involving the dataset
citationIdentifierType	String	The citation identifier type associated with a publication involving the dataset (DOI, arXiv, URL)

PrototypeRelatedDataProduct¶

Type definition for a prototype dataset related data product

Field	Type	Description
dataProductIdq	String	Revisioned, long code for the data product (NEON.DOM.SITE.DP1.00001.001, etc.)
dataProductCode	String	Revisioned, shortened code for the data product (DP1.00001.001, DP1.10072.001, etc.)
dataProductName	String	The name of the data product
dataProductDescription	String	A brief description of the data product

Site¶

Type definition for a site

Field	Type	Description
siteCode	String	Four character code for the site
siteName	String	Full name for the site
siteDescription	String	Brief site description
siteType	String	Core or Gradient site
siteLongitude	Float	Point longitude for the site
siteLatitude	Float	Point latitude for the site
stateName	String	Full name of the state or territory that this site is in
stateCode	String	Two letter state code that this site is in
domainName	String	Brief description for the domain this site is in
domainCode	String	Three character domain abbreviation (D01, D02, etc) for the domain this site is in
deimsId	String	Dynamic Ecological Information Management System - Site and dataset registry (DEIMS-SDR) ID for the site, see deims.org
releases	[DataProductRelease]	List of releases associated with the site based on data products available.
dataProducts	[SiteDataProduct]	List of data products and months of available data

SiteDataProduct¶

Type definition for a set of products describing available data associated with a site

Field	Type	Description
dataProductCode	String	Revisioned, shortened code for the data product (DP1.00001.001, DP1.10072.001, etc)
dataProductTitle	String	Full title for the data product.
availableMonths	[String]	List of years and months that products are available. Formatted as YYYY-MM.
availableDataUrls	[String]	List of data urls for products that are available.
availableReleases	[AvailableRelease]	List of available releases and associated months that have available data within the containing site, product combination.

Inputs¶

DataProductFilter¶

Input type for encapsulating data product filter fields

Field	Type	Description
productCodes	[String!]!	The set of product codes to get for
siteCodes	[String!]	The set of site codes to include for each product
startMonth	String	The start month to filter the associated availability to. Formatted as YYYY-MM.
endMonth	String	The end month to filter the associated availability to. Formatted as YYYY-MM.
release	String	The release to filter the set of products and availability to.

LocationQuery¶

Input type for encapsulating location query fields

Field		Type	Description
locationNames		[String!]!	The set of location names to get for

SiteFilter¶

Input type for encapsulating site filter fields

Field	Type	Description
siteCodes	[String!]!	The set of site codes to get for
productCodes	[String!]	The set of product codes to include for each site
startMonth	String	The start month to filter the associated availability to. Formatted as YYYY-MM.
endMonth	String	The end month to filter the associated availability to. Formatted as YYYY-MM.
release	String	The release to filter the set of sites and availability to.

Scalars¶

Type	Description
AnyScalar	The AnyScalar data type represents a union of possible scalar values.
Boolean	Built-in Boolean
DateTime	The DateTime data type represents a date as an ISO formatted date time: yyyy-MM-dd'T'HH:mm:ss'Z'
Float	Built-in Float
Int	Built-in Int
String	Built-in String

Examples¶

The following examples will provide both an example POST request JSON body as well as a GraphiQL query for utilization from the GraphQL Explorer.

Data Products¶

All data products¶

Example

Get all products and include the product code, name, and description for each:

GraphiQL QueryPOST JSON BodycURLHTTPie

query Products {
  products {
    productCode
    productName
    productDescription
  }
}

{
  "query": "query Products {
    products {
      productCode
      productName
      productDescription
    }
  }"
}

curl -H "Content-Type: application/json" -X POST -d " \
{ \
  \"query\": \"query Products { \
    products { \
      productCode \
      productName \
      productDescription \
    } \
  }\" \
} \
" https://data.neonscience.org/graphql >> neon-data-products-graphql.json

http --download --output=neon-data-products-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Products { \
    products { \
      productCode \
      productName \
      productDescription \
    } \
  }"

One or many data products¶

Example

Get one or many data products with availability information.

One product:

GraphiQL QueryPOST JSON BodyHTTPie

query Product {
  product(productCode: "DP1.00001.001") {
    productCode
    productName
    siteCodes {
      siteCode
      availableMonths
    }
  }
}

{
  "query": "query Product {
    product(productCode: \"DP1.00001.001\") {
      productCode
      productName
      siteCodes {
        siteCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-data-product-DP1.00001.001-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Product { \
    product(productCode: \"DP1.00001.001\") { \
      productCode \
      productName \
      siteCodes { \
        siteCode \
        availableMonths \
      } \
    } \
  }"

Many products:
Note that this introduces a new query - filterProducts. Utilizing the DataProductFilter input type as an argument.

GraphiQL QueryPOST JSON BodyHTTPie

# Query editor window
query filterProducts($filter: DataProductFilter!) {
  products: filterProducts(filter: $filter) {
    productCode
    productName
    productDescription
    siteCodes {
      siteCode
      availableMonths
    }
  }
}

# Query variables window
{
  "filter": {
    "productCodes": ["DP1.00001.001", "DP1.00002.001"]
  }
}

{
  "query": "query filterProducts {
    products: filterProducts(
        filter: { 
          productCodes: [\"DP1.00001.001\", \"DP1.00002.001\"]  
        }
    ) {
      productCode
      productName
      productDescription
      siteCodes {
        siteCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-data-product-many-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query filterProducts { \
    products: filterProducts( \
        filter: {  \
          productCodes: [\"DP1.00001.001\", \"DP1.00002.001\"] \
        } \
    ) { \
      productCode \
      productName \
      productDescription \
      siteCodes { \
        siteCode \
        availableMonths \
      } \
    } \
  }"

Filtered data products¶

Example

Get a data product and filter by availability.

Filtered product:

GraphiQL QueryPOST JSON BodyHTTPie

# Query editor window
query filterProducts($filter: DataProductFilter!) {
  products: filterProducts(filter: $filter) {
    productCode
    productName
    productDescription
    siteCodes {
      siteCode
      availableMonths
    }
  }
}

# Query variables window
{
  "filter": {
    "productCodes": ["DP1.00001.001"],
    "siteCodes": ["ABBY"],
    "startMonth": "2019-01",
    "endMonth": "2019-12"
  }
}

{
  "query": "query filterProducts {
    products: filterProducts(
        filter: { 
          productCodes: [\"DP1.00001.001\"],
          siteCodes: [\"ABBY\"],
          startMonth: \"2019-01\",
          endMonth: \"2019-12\"
        }
    ) {
      productCode
      productName
      productDescription
      siteCodes {
        siteCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-data-product-filtered-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query filterProducts { \
    products: filterProducts( \
        filter: {  \
          productCodes: [\"DP1.00001.001\"] \
          siteCodes: [\"ABBY\"], \
          startMonth: \"2019-01\", \
          endMonth: \"2019-12\" \
        } \
    ) { \
      productCode \
      productName \
      productDescription \
      siteCodes { \
        siteCode \
        availableMonths \
      } \
    } \
  }"

Sites¶

All sites¶

Example

Get sites with code, description, latitude, longitude.

GraphiQL QueryPOST JSON BodycURLHTTPie

query Sites {
  sites {
    siteCode
    siteDescription
    siteLatitude
    siteLongitude
  }
}

{
  "query": "query Sites {
    sites {
      siteCode
      siteDescription
      siteLatitude
      siteLongitude
    }
  }"
}

curl -H "Content-Type: application/json" -X POST -d " \
{ \
  \"query\": \"query Sites { \
    products { \
      siteCode \
      siteDescription \
      siteLatitude \
      siteLongitude \
    } \
  }\" \
} \
" https://data.neonscience.org/graphql >> neon-sites-graphql.json

http --download --output=neon-sites-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Sites { \
    sites { \
      siteCode \
      siteDescription \
      siteLatitude \
      siteLongitude \
    } \
  }"

One or many sites¶

Example

Get one or many sites with availability information.

One site:

GraphiQL QueryPOST JSON BodyHTTPie

query Site {
  site(siteCode: "ABBY") {
    siteCode
    siteDescription
    siteLatitude
    siteLongitude
    dataProducts {
      dataProductCode
      availableMonths
    }
  }
}

{
  "query": "query Site {
    site(siteCode: \"ABBY\") {
      siteCode
      siteDescription
      siteLatitude
      siteLongitude
      dataProducts {
        dataProductCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-site-ABBY-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Site { \
    site(siteCode: \"ABBY\") { \
      siteCode \
      siteDescription \
      siteLatitude \
      siteLongitude \
      dataProducts { \
        dataProductCode \
        availableMonths \
      } \
    } \
  }"

Many sites:
Note that this introduces a new query - filterSites. Utilizing the SiteFilter input type as an argument.

GraphiQL QueryPOST JSON BodyHTTPie

# Query editor window
query filterSites($filter: SiteFilter!) {
  sites: filterSites(filter: $filter) {
    siteCode
    siteDescription
    siteLatitude
    siteLongitude
    dataProducts {
      dataProductCode
      availableMonths
    }
  }
}

# Query variables window
{
  "filter": {
    "siteCodes": ["ABBY", "CPER"]
  }
}

{
  "query": "query filterSites {
    sites: filterSites(
        filter: { 
          siteCodes: [\"ABBY\", \"CPER\"]  
        }
    ) {
      siteCode
      siteDescription
      siteLatitude
      siteLongitude
      dataProducts {
        dataProductCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-sites-many-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query filterSites { \
    sites: filterSites( \
        filter: {  \
          siteCodes: [\"ABBY\", \"CPER\"] \
        } \
    ) { \
      siteCode \
      siteDescription \
      siteLatitude \
      siteLongitude \
      dataProducts { \
        dataProductCode \
        availableMonths \
      } \
    } \
  }"

Filtered sites¶

Example

Get a site and filter by availability.

Filtered site:

GraphiQL QueryPOST JSON BodyHTTPie

# Query editor window
query filterSites($filter: SiteFilter!) {
  sites: filterSites(filter: $filter) {
    siteCode
    siteDescription
    siteLatitude
    siteLongitude
    dataProducts {
      dataProductCode
      availableMonths
    }
  }
}

# Query variables window
{
  "filter": {
    "siteCodes": ["ABBY"],
    "productCodes": ["DP1.00001.001"],
    "startMonth": "2019-01",
    "endMonth": "2019-12"
  }
}

{
  "query": "query filterSites {
    sites: filterSites(
        filter: { 
          siteCodes: [\"ABBY\"],
          productCodes: [\"DP1.00001.001\"],
          startMonth: \"2019-01\",
          endMonth: \"2019-12\"
        }
    ) {
      siteCode
      siteDescription
      siteLatitude
      siteLongitude
      dataProducts {
        dataProductCode
        availableMonths
      }
    }
  }"
}

http --download --output=neon-site-filtered-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query filterSites { \
    sites: filterSites( \
        filter: {  \
          siteCodes: [\"ABBY\"], \
          productCodes: [\"DP1.00001.001\"] \
          startMonth: \"2019-01\", \
          endMonth: \"2019-12\" \
        } \
    ) { \
      siteCode \
      siteDescription \
      siteLatitude \
      siteLongitude \
      dataProducts { \
        dataProductCode \
        availableMonths \
      } \
    } \
  }"

Locations¶

Get a location¶

Example

Get location information by name

GraphiQL QueryPOST JSON BodyHTTPie

query Location {
  location(name: "ABBY") {
    locationName
    locationDescription
    locationType
    domainCode
    siteCode
    locationDecimalLatitude
    locationDecimalLongitude
    locationElevation
    locationUtmEasting
    locationUtmNorthing
    locationUtmHemisphere
    locationUtmZone
    alphaOrientation
    betaOrientation
    gammaOrientation
    xOffset
    yOffset
    zOffset
    locationProperties {
      locationPropertyName
      locationPropertyValue
    }
  }
}

{
  "query": "query Location {
    location(name: \"ABBY\") {
      locationName
      locationDescription
      locationType
      domainCode
      siteCode
      locationDecimalLatitude
      locationDecimalLongitude
      locationElevation
      locationUtmEasting
      locationUtmNorthing
      locationUtmHemisphere
      locationUtmZone
      alphaOrientation
      betaOrientation
      gammaOrientation
      xOffset
      yOffset
      zOffset
      locationProperties {
        locationPropertyName
        locationPropertyValue
      }
    }
  }"
}

http --download --output=neon-location-ABBY-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query Location { \
    location(name: \"ABBY\") { \
      locationName \
      locationDescription \
      locationType \
      domainCode \
      siteCode \
      locationDecimalLatitude \
      locationDecimalLongitude \
      locationElevation \
      locationUtmEasting \
      locationUtmNorthing \
      locationUtmHemisphere \
      locationUtmZone \
      alphaOrientation \
      betaOrientation \
      gammaOrientation \
      xOffset \
      yOffset \
      zOffset \
      locationProperties { \
        locationPropertyName \
        locationPropertyValue \
      } \
    } \
  }"

Find locations¶

Example

Get a set of locations by name

Find locations query:

GraphiQL QueryPOST JSON BodyHTTPie

# Query editor window
query findLocations($query: LocationQuery!) {
  locations: findLocations(query: $query) {
    locationName
    locationDescription
    locationType
    domainCode
    siteCode
    locationDecimalLatitude
    locationDecimalLongitude
    locationElevation
  }
}

# Query variables window
{
  "query": {
    "locationNames": ["D10", "CPER", "ARIK"]
  }
}

{
  "query": "query findLocations {
    locations: findLocations(
        query: { 
          locationNames: [\"D10\", \"CPER\", \"ARIK\"]
        }
    ) {
      locationName
      locationDescription
      locationType
      domainCode
      siteCode
      locationDecimalLatitude
      locationDecimalLongitude
      locationElevation
    }
  }"
}

http --download --output=neon-locations-graphql.json \
  POST https://data.neonscience.org/graphql \
  Content-Type:application/json \
  query="query findLocations { \
    locations: findLocations( \
        query: {  \
          locationNames: [\"D10\", \"CPER\", \"ARIK\"] \
        } \
    ) { \
      locationName \
      locationDescription \
      locationType \
      domainCode \
      siteCode \
      locationDecimalLatitude \
      locationDecimalLongitude \
      locationElevation \
    } \
  }"

Resources¶

For a deeper dive into GraphQL concepts:

HTTPie CLI Tool:

httpie.org

GraphQL API¶

Using GraphQL¶

REST API¶

GraphQL Query¶

Endpoint Definition¶

POST /graphql¶

Description¶

Queries¶

Objects¶

ActivePeriod¶

AvailableRelease¶

Coordinate¶

DataProduct¶

DataProductDoi¶

DataProductRelease¶

DataProductSite¶

DataProductSpec¶

Location¶

LocationChildHierarhcy¶

LocationHistory¶

LocationParentHierarchy¶

LocationProperty¶

Polygon¶

PrototypeData¶

PrototypeDataFile¶

PrototypeDataFileType¶

PrototypeDataLocation¶

PrototypeDataset¶

PrototypeDatasetDoi¶

PrototypeDatasetRelatedVersion¶

PrototypeFileType¶

PrototypeLocation¶

PrototypePublicationCitation¶

PrototypeRelatedDataProduct¶

Site¶

SiteDataProduct¶

Inputs¶

DataProductFilter¶

LocationQuery¶

SiteFilter¶

Scalars¶

Examples¶

Data Products¶

All data products¶

One or many data products¶

Filtered data products¶

Sites¶

All sites¶

One or many sites¶

Filtered sites¶

Locations¶

Get a location¶

Find locations¶

Resources¶

POST `/graphql`¶