diff --git a/docs/content/data-use-policy.md b/docs/content/data-use-policy.md
index bd7b5e5..a6e7f7e 100644
--- a/docs/content/data-use-policy.md
+++ b/docs/content/data-use-policy.md
@@ -1,5 +1,6 @@
# NEON Data Use and Citation Policy
-For more information on NEON Data Use and Citation Policy visit our
-[About Data Policies](https://www.neonscience.org/data-samples/data-policies-citation)
-page.
+For more information on NEON Data Use and Citation Policies visit our
+[Data Guidelines and Policies](https://www.neonscience.org/data-samples/guidelines-policies) page.
+
+
\ No newline at end of file
diff --git a/docs/content/index.md b/docs/content/index.md
index ea2fa95..737d765 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -1,23 +1,26 @@
-# Welcome to the NEON Data API
+# NEON Data API
## **Introduction**
-
-The NEON Data API (Application Programming Interface) can be used to quickly access data as well as information about our data products, samples, 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)](https://json.org/json-en.html).
-
+The NEON Data API (Application Programming Interface) can be used to quickly access data as well as information about NEON's data products, samples, and sampling locations. It provides a simple means of constructing URLs or cURL statements that return information in a common machine-readable format, [JSON (JavaScript Object Notation)](https://json.org/json-en.html).
+
+## **R & Python packages**
+The neonUtilities packages are the easiest way to download and reformat NEON data.
+ * [`neonUtilities` R package](https://cran.r-project.org/web/packages/neonUtilities/index.html)
+ * [`neonutilities` Python package](https://pypi.org/project/neonutilities)
+ * Check out the ["Use the neonUtilities Package to Access NEON Data" tutorial](https://www.neonscience.org/resources/learning-hub/tutorials/neondatastackr)
+
+## **REST API Explorer**
The API provides numerous endpoints, some of which provide the option to enter values for specific parameters that allow you to refine your search. To learn more about each endpoint, click on “REST API Endpoints” in the navigation menu. To try each endpoint out, open the [REST API Explorer](https://data.neonscience.org/data-api/explorer/).
-In addition to providing REST API endpoints, the NEON Data API also provides a [GraphQL](https://data.neonscience.org/data-api/graphql/) endpoint, allowing users to take advantage of the flexibility and efficiency of the [GraphQL data query language](https://graphql.org/) to access NEON metadata. The `/graphql` endpoint affords users the ability to define and receive only desired metadata.
-
-If you need more information, try visiting our
-
- * [GitHub repository](https://github.com/NEONScience/neon-data-api),
- * [Using the NEON API tutorial](https://www.neonscience.org/neon-api-usage), or
- * [FAQ](https://www.neonscience.org/faq).
-
-We also provide an [R package](https://cran.r-project.org/web/packages/neonUtilities/index.html), called `neonUtilities`, that you can use to download and reformat the data.
-
-## **Feedback**
+## **GraphQL**
+The [GraphQL](https://data.neonscience.org/data-api/graphql/) endpoint allows users to take advantage of the flexibility and efficiency of the [GraphQL data query language](https://graphql.org/) to access NEON metadata. The `/graphql` endpoint affords users the ability to define and receive only desired metadata.
-**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](https://github.com/NEONScience/neon-data-api/issues) and tell us about it!
+## **Other Resources**
+ * [The NEON Data API GitHub repository](https://github.com/NEONScience/neon-data-api),
+ * [Using the NEON API tutorial](https://www.neonscience.org/neon-api-usage)
+ * Download the [Swagger documentation](https://raw.githubusercontent.com/NEONScience/neon-data-api/refs/heads/main/packages/docs-app-swagger/src/swagger.json)
+
+## **Provide Feedback**
+If you have design ideas, functionality requests, bug notes, examples of how you used the API, etc., please [contact us](https://www.neonscience.org/about/contact-us).
diff --git a/mkdocs.yml b/mkdocs.yml
index 67b9337..ba4a589 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,20 +44,20 @@ extra_css:
# Nav items
nav:
- Home: 'https://www.neonscience.org'
- - Data Portal: 'https://www.neonscience.org/data'
+ - Data Portal: 'https://data.neonscience.org/data-products/explore'
- NEON Data API:
- 'About': index.md
- - 'REST API':
+ - 'REST API Explorer & Endpoints':
+ - 'REST API Explorer': 'explorer/index.md'
- 'Products': 'endpoints/products.md'
- 'Sites': 'endpoints/sites.md'
- - 'Releases': 'endpoints/releases.md'
+ - 'Locations': 'endpoints/locations.md'
- 'Data': 'endpoints/data.md'
- 'Data Query': 'endpoints/data-query.md'
- - 'Locations': 'endpoints/locations.md'
- - 'Taxonomy': 'endpoints/taxonomy.md'
+ - 'Releases': 'endpoints/releases.md'
- 'Samples': 'endpoints/samples.md'
+ - 'Taxonomy': 'endpoints/taxonomy.md'
- 'Prototype Datasets': 'endpoints/prototype-datasets.md'
- - 'REST API Explorer': 'explorer/index.md'
- 'GraphQL API':
- 'Overview': 'graphql/index.md'
- 'GraphQL Explorer': 'graphql/explorer/index.md'
diff --git a/packages/docs-app-swagger/src/swagger.json b/packages/docs-app-swagger/src/swagger.json
index bb5dde9..4168679 100644
--- a/packages/docs-app-swagger/src/swagger.json
+++ b/packages/docs-app-swagger/src/swagger.json
@@ -219,75 +219,70 @@
}
}
},
- "/releases": {
- "get": {
- "description": "Get information about all available data releases",
- "tags": [
- "Releases"
- ],
- "operationId": "Get_releases_",
- "produces": [
- "application/json"
- ],
- "responses": {
- "200": {
- "description": "List of data releases",
- "schema": {
- "type": "object",
- "properties": {
- "data": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/release"
- }
- }
- }
- }
- },
- "default": {
- "description": "General error",
- "schema": {
- "$ref": "#/definitions/error"
- }
- }
- }
- }
- },
- "/releases/{releaseIdentifier}": {
+ "/locations/{locationName}": {
"get": {
- "description": "Get information about a data release",
+ "description": "Get information about a location",
"tags": [
- "Releases"
+ "Locations"
],
- "operationId": "Get_releases_releaseIdentifier_",
+ "operationId": "Get_locations:locationName_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "releaseIdentifier",
+ "name": "locationName",
"in": "path",
- "description": "Release tag or UUID to get information for",
+ "description": "Location to get",
"required": true,
"type": "string"
+ },
+ {
+ "name": "history",
+ "in": "query",
+ "description": "Option to obtain location history information",
+ "required": false,
+ "type": "boolean"
+ },
+ {
+ "name": "hierarchy",
+ "in": "query",
+ "description": "Option to obtain location hierarchy information",
+ "required": false,
+ "type": "boolean"
+ },
+ {
+ "name": "locationType",
+ "in": "query",
+ "description": "\"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\"",
+ "required": false,
+ "type": "string"
}
],
"responses": {
"200": {
- "description": "Single data release",
+ "description": "Single location",
"schema": {
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/release"
+ "$ref": "#/definitions/location"
}
}
}
},
"400": {
- "description": "Release(s) not found",
+ "description": "Location(s) not found",
"schema": {
- "$ref": "#/definitions/error"
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/error"
+ }
+ }
+ }
}
},
"default": {
@@ -299,35 +294,27 @@
}
}
},
- "/releases/{releaseTag}/products": {
+ "/locations/sites": {
"get": {
- "description": "Get information about all data products within a specific release",
+ "description": "Get information about the site-level locations",
"tags": [
- "Releases"
+ "Locations",
+ "Sites"
],
- "operationId": "Get_releases_products_",
+ "operationId": "Get_locations_sites_",
"produces": [
"application/json"
],
- "parameters": [
- {
- "name": "releaseTag",
- "in": "path",
- "description": "The name of the release to get availability for",
- "required": true,
- "type": "string"
- }
- ],
"responses": {
"200": {
- "description": "List of data products",
+ "description": "List of locations",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
- "$ref": "#/definitions/product"
+ "$ref": "#/definitions/location"
}
}
}
@@ -342,136 +329,71 @@
}
}
},
- "/releases/{releaseTag}/products/{productCode}": {
+ "/data/{productCode}/{siteCode}/{year-month}": {
"get": {
- "description": "Get information about a data product within a specific release",
+ "description": "Get files available for a given product/site/month combination",
"tags": [
- "Releases"
+ "Data"
],
- "operationId": "Get_releases_products_productCode_",
+ "operationId": "Get_data:availability_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "releaseTag",
+ "name": "productCode",
"in": "path",
- "description": "The name of the release to get availability for",
+ "description": "Product to check for files",
"required": true,
"type": "string"
},
{
- "name": "productCode",
+ "name": "siteCode",
"in": "path",
- "description": "Data product to get",
+ "description": "Site to check for files",
"required": true,
"type": "string"
- }
- ],
- "responses": {
- "200": {
- "description": "Single data product",
- "schema": {
- "type": "object",
- "properties": {
- "data": {
- "$ref": "#/definitions/product"
- }
- }
- }
- },
- "400": {
- "description": "Product(s) not found",
- "schema": {
- "$ref": "#/definitions/error"
- }
},
- "default": {
- "description": "General error",
- "schema": {
- "$ref": "#/definitions/error"
- }
- }
- }
- }
- },
- "/releases/{releaseTag}/sites": {
- "get": {
- "description": "Get information about all sites within a specific release",
- "tags": [
- "Releases"
- ],
- "operationId": "Get_releases_sites_",
- "produces": [
- "application/json"
- ],
- "parameters": [
{
- "name": "releaseTag",
+ "name": "year-month",
"in": "path",
- "description": "The name of the release to get availability for",
+ "description": "YYYY-MM month to check for files",
"required": true,
"type": "string"
- }
- ],
- "responses": {
- "200": {
- "description": "List of sites",
- "schema": {
- "type": "object",
- "properties": {
- "data": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/site"
- }
- }
- }
- }
- }
- }
- }
- },
- "/releases/{releaseTag}/sites/{siteCode}": {
- "get": {
- "description": "Get information about a field site within a specific release",
- "tags": [
- "Releases"
- ],
- "operationId": "Get_releases_sites:siteCode_",
- "produces": [
- "application/json"
- ],
- "parameters": [
+ },
{
- "name": "releaseTag",
- "in": "path",
- "description": "The name of the release to get availability for",
- "required": true,
- "type": "string"
+ "name": "package",
+ "in": "query",
+ "description": "Package type to return, basic or expanded",
+ "required": false,
+ "type": "string",
+ "enum": [
+ "basic",
+ "expanded"
+ ]
},
{
- "name": "siteCode",
- "in": "path",
- "description": "Site to get",
- "required": true,
+ "name": "release",
+ "in": "query",
+ "description": "The name of the release to get for",
+ "required": false,
"type": "string"
}
],
"responses": {
"200": {
- "description": "Single site",
+ "description": "Available files",
"schema": {
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/site"
+ "$ref": "#/definitions/data"
}
}
}
},
"400": {
- "description": "Site(s) not found",
+ "description": "Product, site not found or invalid date range specified",
"schema": {
"type": "object",
"properties": {
@@ -493,24 +415,17 @@
}
}
},
- "/releases/{releaseTag}/data/{productCode}/{siteCode}/{year-month}": {
+ "/data/{productCode}/{siteCode}/{year-month}/{filename}": {
"get": {
- "description": "Get files available for a given release and product/site/month combination",
+ "description": "Get a file for a given product/site/month/filename combination",
"tags": [
- "Releases"
+ "Data"
],
- "operationId": "Get_releases_data:availability_",
+ "operationId": "Get_data:availability_file_",
"produces": [
- "application/json"
+ "application/octet-stream"
],
"parameters": [
- {
- "name": "releaseTag",
- "in": "path",
- "description": "The name of the release to get availability for",
- "required": true,
- "type": "string"
- },
{
"name": "productCode",
"in": "path",
@@ -532,6 +447,13 @@
"required": true,
"type": "string"
},
+ {
+ "name": "filename",
+ "in": "path",
+ "description": "The name of the file",
+ "required": true,
+ "type": "string"
+ },
{
"name": "package",
"in": "query",
@@ -542,22 +464,32 @@
"basic",
"expanded"
]
+ },
+ {
+ "name": "release",
+ "in": "query",
+ "description": "The name of the release to get for",
+ "required": false,
+ "type": "string"
}
],
"responses": {
"200": {
- "description": "Available files",
+ "description": "Available file data",
"schema": {
- "type": "object",
- "properties": {
- "data": {
- "$ref": "#/definitions/data"
- }
- }
+ "type": "string",
+ "format": "binary"
+ }
+ },
+ "302": {
+ "description": "Found available file and redirects to data",
+ "schema": {
+ "type": "string",
+ "format": "binary"
}
},
"400": {
- "description": "Product, site not found or invalid date range specified",
+ "description": "Invalid file name specified",
"schema": {
"type": "object",
"properties": {
@@ -579,24 +511,17 @@
}
}
},
- "/releases/{releaseTag}/data/{productCode}/{siteCode}/{year-month}/{filename}": {
+ "/data/package/{productCode}/{siteCode}/{year-month}": {
"get": {
- "description": "Get a file for a given release and product/site/month/filename combination",
+ "description": "Get a data package for a given product/site/month and package combination",
"tags": [
- "Releases"
+ "Data"
],
- "operationId": "Get_releases_data:availability_file_",
+ "operationId": "Get_data:availability_package_",
"produces": [
- "application/octet-stream"
+ "application/zip"
],
"parameters": [
- {
- "name": "releaseTag",
- "in": "path",
- "description": "The name of the release to get availability for",
- "required": true,
- "type": "string"
- },
{
"name": "productCode",
"in": "path",
@@ -618,13 +543,6 @@
"required": true,
"type": "string"
},
- {
- "name": "filename",
- "in": "path",
- "description": "The name of the file",
- "required": true,
- "type": "string"
- },
{
"name": "package",
"in": "query",
@@ -635,25 +553,29 @@
"basic",
"expanded"
]
+ },
+ {
+ "name": "release",
+ "in": "query",
+ "description": "The name of the release to get for",
+ "required": false,
+ "type": "string"
}
],
"responses": {
"200": {
- "description": "Available file data",
- "schema": {
- "type": "string",
- "format": "binary"
- }
- },
- "302": {
- "description": "Found available file and redirects to data",
- "schema": {
- "type": "string",
- "format": "binary"
+ "description": "Available data package as zip",
+ "content": {
+ "application/zip": {
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ }
}
},
"400": {
- "description": "Invalid file name specified",
+ "description": "Invalid product, site, or month specified",
"schema": {
"type": "object",
"properties": {
@@ -675,71 +597,85 @@
}
}
},
- "/releases/{releaseTag}/data/package/{productCode}/{siteCode}/{year-month}": {
+ "/data/query": {
"get": {
- "description": "Get a data package for a given release and product/site/month and package combination",
+ "description": "Get files available for a given product, one or more sites, date range, release, package combination",
"tags": [
- "Releases"
+ "Data Query"
],
- "operationId": "Get_releases_data:availability_package_",
+ "operationId": "Get_data_query:availability_",
"produces": [
- "application/zip"
+ "application/json"
],
"parameters": [
{
- "name": "releaseTag",
- "in": "path",
- "description": "The name of the release to get availability for",
+ "name": "productCode",
+ "in": "query",
+ "description": "Product code to query for files",
"required": true,
"type": "string"
},
{
- "name": "productCode",
- "in": "path",
- "description": "Product to check for files",
+ "name": "siteCode",
+ "in": "query",
+ "description": "One or more four letter site codes to query for files",
"required": true,
"type": "string"
},
{
- "name": "siteCode",
- "in": "path",
- "description": "Site to check for files",
+ "name": "startDateMonth",
+ "in": "query",
+ "description": "YYYY-MM start date month to query for files",
"required": true,
"type": "string"
},
{
- "name": "year-month",
- "in": "path",
- "description": "YYYY-MM month to check for files",
+ "name": "endDateMonth",
+ "in": "query",
+ "description": "YYYY-MM end date month to query for files",
"required": true,
"type": "string"
},
+ {
+ "name": "release",
+ "in": "query",
+ "description": "The name of the release to query for",
+ "required": false,
+ "type": "string"
+ },
{
"name": "package",
"in": "query",
- "description": "Package type to return, basic or expanded",
+ "description": "Package type to query, basic or expanded",
"required": false,
"type": "string",
"enum": [
"basic",
"expanded"
]
+ },
+ {
+ "name": "includeProvisional",
+ "in": "query",
+ "description": "Optionally include provisional data in the query",
+ "required": false,
+ "type": "boolean"
}
],
"responses": {
"200": {
- "description": "Available data package as zip",
- "content": {
- "application/zip": {
- "schema": {
- "type": "string",
- "format": "binary"
+ "description": "Available files",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/dataQuery"
}
}
}
},
"400": {
- "description": "Invalid product, site, or month specified",
+ "description": "One or more invalid paramaters specified",
"schema": {
"type": "object",
"properties": {
@@ -759,57 +695,70 @@
}
}
}
- }
- },
- "/data/{productCode}/{siteCode}/{year-month}": {
- "get": {
- "description": "Get files available for a given product/site/month combination",
+ },
+ "post": {
+ "description": "Get files available for a given product, one or more sites, date range, release, package combination",
"tags": [
- "Data"
+ "Data Query"
+ ],
+ "operationId": "Post_data_query:availability_",
+ "consumes": [
+ "application/json"
],
- "operationId": "Get_data:availability_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "productCode",
- "in": "path",
- "description": "Product to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "siteCode",
- "in": "path",
- "description": "Site to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "year-month",
- "in": "path",
- "description": "YYYY-MM month to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "package",
- "in": "query",
- "description": "Package type to return, basic or expanded",
- "required": false,
- "type": "string",
- "enum": [
- "basic",
- "expanded"
- ]
- },
- {
- "name": "release",
- "in": "query",
- "description": "The name of the release to get for",
- "required": false,
- "type": "string"
+ "name": "DataQueryRequest",
+ "in": "body",
+ "description": "The data query request",
+ "schema": {
+ "type": "object",
+ "required": [
+ "productCode",
+ "siteCodes",
+ "startDateMonth",
+ "endDateMonth"
+ ],
+ "properties": {
+ "productCode": {
+ "type": "string",
+ "description": "Product code to query for files"
+ },
+ "siteCodes": {
+ "type": "array",
+ "description": "One or more four letter site codes to query for files",
+ "items": {
+ "type": "string"
+ }
+ },
+ "startDateMonth": {
+ "type": "string",
+ "description": "YYYY-MM start date month to query for files"
+ },
+ "endDateMonth": {
+ "type": "string",
+ "description": "YYYY-MM end date month to query for files"
+ },
+ "release": {
+ "type": "string",
+ "description": "The name of the release to query for"
+ },
+ "package": {
+ "type": "string",
+ "description": "Package type to query, basic or expanded",
+ "enum": [
+ "basic",
+ "expanded"
+ ]
+ },
+ "includeProvisional": {
+ "type": "boolean",
+ "description": "Optionally include provisional data in the query"
+ }
+ }
+ }
}
],
"responses": {
@@ -819,13 +768,13 @@
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/data"
+ "$ref": "#/definitions/dataQuery"
}
}
}
},
"400": {
- "description": "Product, site not found or invalid date range specified",
+ "description": "One or more invalid paramaters specified",
"schema": {
"type": "object",
"properties": {
@@ -847,88 +796,26 @@
}
}
},
- "/data/{productCode}/{siteCode}/{year-month}/{filename}": {
+ "/releases": {
"get": {
- "description": "Get a file for a given product/site/month/filename combination",
+ "description": "Get information about all available data releases",
"tags": [
- "Data"
+ "Releases"
],
- "operationId": "Get_data:availability_file_",
+ "operationId": "Get_releases_",
"produces": [
- "application/octet-stream"
- ],
- "parameters": [
- {
- "name": "productCode",
- "in": "path",
- "description": "Product to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "siteCode",
- "in": "path",
- "description": "Site to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "year-month",
- "in": "path",
- "description": "YYYY-MM month to check for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "filename",
- "in": "path",
- "description": "The name of the file",
- "required": true,
- "type": "string"
- },
- {
- "name": "package",
- "in": "query",
- "description": "Package type to return, basic or expanded",
- "required": false,
- "type": "string",
- "enum": [
- "basic",
- "expanded"
- ]
- },
- {
- "name": "release",
- "in": "query",
- "description": "The name of the release to get for",
- "required": false,
- "type": "string"
- }
+ "application/json"
],
"responses": {
"200": {
- "description": "Available file data",
- "schema": {
- "type": "string",
- "format": "binary"
- }
- },
- "302": {
- "description": "Found available file and redirects to data",
- "schema": {
- "type": "string",
- "format": "binary"
- }
- },
- "400": {
- "description": "Invalid file name specified",
+ "description": "List of data releases",
"schema": {
"type": "object",
"properties": {
- "errors": {
+ "data": {
"type": "array",
"items": {
- "$ref": "#/definitions/error"
+ "$ref": "#/definitions/release"
}
}
}
@@ -943,78 +830,81 @@
}
}
},
- "/data/package/{productCode}/{siteCode}/{year-month}": {
+ "/releases/{releaseIdentifier}": {
"get": {
- "description": "Get a data package for a given product/site/month and package combination",
+ "description": "Get information about a data release",
"tags": [
- "Data"
+ "Releases"
],
- "operationId": "Get_data:availability_package_",
+ "operationId": "Get_releases_releaseIdentifier_",
"produces": [
- "application/zip"
+ "application/json"
],
"parameters": [
{
- "name": "productCode",
+ "name": "releaseIdentifier",
"in": "path",
- "description": "Product to check for files",
+ "description": "Release tag or UUID to get information for",
"required": true,
"type": "string"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "Single data release",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "$ref": "#/definitions/release"
+ }
+ }
+ }
},
- {
- "name": "siteCode",
- "in": "path",
- "description": "Site to check for files",
- "required": true,
- "type": "string"
+ "400": {
+ "description": "Release(s) not found",
+ "schema": {
+ "$ref": "#/definitions/error"
+ }
},
+ "default": {
+ "description": "General error",
+ "schema": {
+ "$ref": "#/definitions/error"
+ }
+ }
+ }
+ }
+ },
+ "/releases/{releaseTag}/products": {
+ "get": {
+ "description": "Get information about all data products within a specific release",
+ "tags": [
+ "Releases"
+ ],
+ "operationId": "Get_releases_products_",
+ "produces": [
+ "application/json"
+ ],
+ "parameters": [
{
- "name": "year-month",
+ "name": "releaseTag",
"in": "path",
- "description": "YYYY-MM month to check for files",
+ "description": "The name of the release to get availability for",
"required": true,
"type": "string"
- },
- {
- "name": "package",
- "in": "query",
- "description": "Package type to return, basic or expanded",
- "required": false,
- "type": "string",
- "enum": [
- "basic",
- "expanded"
- ]
- },
- {
- "name": "release",
- "in": "query",
- "description": "The name of the release to get for",
- "required": false,
- "type": "string"
}
],
"responses": {
"200": {
- "description": "Available data package as zip",
- "content": {
- "application/zip": {
- "schema": {
- "type": "string",
- "format": "binary"
- }
- }
- }
- },
- "400": {
- "description": "Invalid product, site, or month specified",
+ "description": "List of data products",
"schema": {
"type": "object",
"properties": {
- "errors": {
+ "data": {
"type": "array",
"items": {
- "$ref": "#/definitions/error"
+ "$ref": "#/definitions/product"
}
}
}
@@ -1029,95 +919,48 @@
}
}
},
- "/data/query": {
+ "/releases/{releaseTag}/products/{productCode}": {
"get": {
- "description": "Get files available for a given product, one or more sites, date range, release, package combination",
+ "description": "Get information about a data product within a specific release",
"tags": [
- "Data Query"
+ "Releases"
],
- "operationId": "Get_data_query:availability_",
+ "operationId": "Get_releases_products_productCode_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "productCode",
- "in": "query",
- "description": "Product code to query for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "siteCode",
- "in": "query",
- "description": "One or more four letter site codes to query for files",
- "required": true,
- "type": "string"
- },
- {
- "name": "startDateMonth",
- "in": "query",
- "description": "YYYY-MM start date month to query for files",
+ "name": "releaseTag",
+ "in": "path",
+ "description": "The name of the release to get availability for",
"required": true,
"type": "string"
},
{
- "name": "endDateMonth",
- "in": "query",
- "description": "YYYY-MM end date month to query for files",
+ "name": "productCode",
+ "in": "path",
+ "description": "Data product to get",
"required": true,
"type": "string"
- },
- {
- "name": "release",
- "in": "query",
- "description": "The name of the release to query for",
- "required": false,
- "type": "string"
- },
- {
- "name": "package",
- "in": "query",
- "description": "Package type to query, basic or expanded",
- "required": false,
- "type": "string",
- "enum": [
- "basic",
- "expanded"
- ]
- },
- {
- "name": "includeProvisional",
- "in": "query",
- "description": "Optionally include provisional data in the query",
- "required": false,
- "type": "boolean"
}
],
"responses": {
"200": {
- "description": "Available files",
+ "description": "Single data product",
"schema": {
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/dataQuery"
+ "$ref": "#/definitions/product"
}
}
}
},
"400": {
- "description": "One or more invalid paramaters specified",
+ "description": "Product(s) not found",
"schema": {
- "type": "object",
- "properties": {
- "errors": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/error"
- }
- }
- }
+ "$ref": "#/definitions/error"
}
},
"default": {
@@ -1127,86 +970,85 @@
}
}
}
- },
- "post": {
- "description": "Get files available for a given product, one or more sites, date range, release, package combination",
+ }
+ },
+ "/releases/{releaseTag}/sites": {
+ "get": {
+ "description": "Get information about all sites within a specific release",
"tags": [
- "Data Query"
- ],
- "operationId": "Post_data_query:availability_",
- "consumes": [
- "application/json"
+ "Releases"
],
+ "operationId": "Get_releases_sites_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "DataQueryRequest",
- "in": "body",
- "description": "The data query request",
- "schema": {
- "type": "object",
- "required": [
- "productCode",
- "siteCodes",
- "startDateMonth",
- "endDateMonth"
- ],
- "properties": {
- "productCode": {
- "type": "string",
- "description": "Product code to query for files"
- },
- "siteCodes": {
- "type": "array",
- "description": "One or more four letter site codes to query for files",
- "items": {
- "type": "string"
- }
- },
- "startDateMonth": {
- "type": "string",
- "description": "YYYY-MM start date month to query for files"
- },
- "endDateMonth": {
- "type": "string",
- "description": "YYYY-MM end date month to query for files"
- },
- "release": {
- "type": "string",
- "description": "The name of the release to query for"
- },
- "package": {
- "type": "string",
- "description": "Package type to query, basic or expanded",
- "enum": [
- "basic",
- "expanded"
- ]
- },
- "includeProvisional": {
- "type": "boolean",
- "description": "Optionally include provisional data in the query"
+ "name": "releaseTag",
+ "in": "path",
+ "description": "The name of the release to get availability for",
+ "required": true,
+ "type": "string"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "List of sites",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/site"
+ }
}
}
}
}
+ }
+ }
+ },
+ "/releases/{releaseTag}/sites/{siteCode}": {
+ "get": {
+ "description": "Get information about a field site within a specific release",
+ "tags": [
+ "Releases"
+ ],
+ "operationId": "Get_releases_sites:siteCode_",
+ "produces": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "releaseTag",
+ "in": "path",
+ "description": "The name of the release to get availability for",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "siteCode",
+ "in": "path",
+ "description": "Site to get",
+ "required": true,
+ "type": "string"
+ }
],
"responses": {
"200": {
- "description": "Available files",
+ "description": "Single site",
"schema": {
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/dataQuery"
+ "$ref": "#/definitions/site"
}
}
}
},
"400": {
- "description": "One or more invalid paramaters specified",
+ "description": "Site(s) not found",
"schema": {
"type": "object",
"properties": {
@@ -1228,60 +1070,71 @@
}
}
},
- "/locations/{locationName}": {
+ "/releases/{releaseTag}/data/{productCode}/{siteCode}/{year-month}": {
"get": {
- "description": "Get information about a location",
+ "description": "Get files available for a given release and product/site/month combination",
"tags": [
- "Locations"
+ "Releases"
],
- "operationId": "Get_locations:locationName_",
+ "operationId": "Get_releases_data:availability_",
"produces": [
"application/json"
],
"parameters": [
{
- "name": "locationName",
+ "name": "releaseTag",
"in": "path",
- "description": "Location to get",
+ "description": "The name of the release to get availability for",
"required": true,
"type": "string"
},
{
- "name": "history",
- "in": "query",
- "description": "Option to obtain location history information",
- "required": false,
- "type": "boolean"
+ "name": "productCode",
+ "in": "path",
+ "description": "Product to check for files",
+ "required": true,
+ "type": "string"
},
{
- "name": "hierarchy",
- "in": "query",
- "description": "Option to obtain location hierarchy information",
- "required": false,
- "type": "boolean"
+ "name": "siteCode",
+ "in": "path",
+ "description": "Site to check for files",
+ "required": true,
+ "type": "string"
},
{
- "name": "locationType",
+ "name": "year-month",
+ "in": "path",
+ "description": "YYYY-MM month to check for files",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "package",
"in": "query",
- "description": "\"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\"",
+ "description": "Package type to return, basic or expanded",
"required": false,
- "type": "string"
+ "type": "string",
+ "enum": [
+ "basic",
+ "expanded"
+ ]
}
],
"responses": {
"200": {
- "description": "Single location",
+ "description": "Available files",
"schema": {
"type": "object",
"properties": {
"data": {
- "$ref": "#/definitions/location"
+ "$ref": "#/definitions/data"
}
}
}
},
"400": {
- "description": "Location(s) not found",
+ "description": "Product, site not found or invalid date range specified",
"schema": {
"type": "object",
"properties": {
@@ -1303,27 +1156,88 @@
}
}
},
- "/locations/sites": {
+ "/releases/{releaseTag}/data/{productCode}/{siteCode}/{year-month}/{filename}": {
"get": {
- "description": "Get information about the site-level locations",
+ "description": "Get a file for a given release and product/site/month/filename combination",
"tags": [
- "Locations",
- "Sites"
+ "Releases"
],
- "operationId": "Get_locations_sites_",
+ "operationId": "Get_releases_data:availability_file_",
"produces": [
- "application/json"
+ "application/octet-stream"
+ ],
+ "parameters": [
+ {
+ "name": "releaseTag",
+ "in": "path",
+ "description": "The name of the release to get availability for",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "productCode",
+ "in": "path",
+ "description": "Product to check for files",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "siteCode",
+ "in": "path",
+ "description": "Site to check for files",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "year-month",
+ "in": "path",
+ "description": "YYYY-MM month to check for files",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "filename",
+ "in": "path",
+ "description": "The name of the file",
+ "required": true,
+ "type": "string"
+ },
+ {
+ "name": "package",
+ "in": "query",
+ "description": "Package type to return, basic or expanded",
+ "required": false,
+ "type": "string",
+ "enum": [
+ "basic",
+ "expanded"
+ ]
+ }
],
"responses": {
"200": {
- "description": "List of locations",
+ "description": "Available file data",
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ },
+ "302": {
+ "description": "Found available file and redirects to data",
+ "schema": {
+ "type": "string",
+ "format": "binary"
+ }
+ },
+ "400": {
+ "description": "Invalid file name specified",
"schema": {
"type": "object",
"properties": {
- "data": {
+ "errors": {
"type": "array",
"items": {
- "$ref": "#/definitions/location"
+ "$ref": "#/definitions/error"
}
}
}
@@ -1338,157 +1252,71 @@
}
}
},
- "/taxonomy": {
+ "/releases/{releaseTag}/data/package/{productCode}/{siteCode}/{year-month}": {
"get": {
- "description": "Get taxonomic lists",
+ "description": "Get a data package for a given release and product/site/month and package combination",
"tags": [
- "Taxonomy"
+ "Releases"
],
- "operationId": "Get_taxonomy",
+ "operationId": "Get_releases_data:availability_package_",
"produces": [
- "application/json"
+ "application/zip"
],
"parameters": [
{
- "name": "taxonTypeCode",
- "in": "query",
- "description": "Taxon type code to get. Must not be used in conjunction with a taxon rank query parameter.",
- "required": false,
- "enum": [
- "ALGAE",
- "BEETLE",
- "BIRD",
- "FISH",
- "HERPETOLOGY",
- "MACROINVERTEBRATE",
- "MOSQUITO",
- "MOSQUITO_PATHOGENS",
- "SMALL_MAMMAL",
- "PLANT",
- "TICK"
- ],
- "type": "string"
- },
- {
- "name": "kingdom",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
- "type": "string"
- },
- {
- "name": "phylum",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
- "type": "string"
- },
- {
- "name": "division",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
- "type": "string"
- },
- {
- "name": "order",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
- "type": "string"
- },
- {
- "name": "class",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
- "type": "string"
- },
- {
- "name": "family",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
+ "name": "releaseTag",
+ "in": "path",
+ "description": "The name of the release to get availability for",
+ "required": true,
"type": "string"
},
{
- "name": "genus",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
+ "name": "productCode",
+ "in": "path",
+ "description": "Product to check for files",
+ "required": true,
"type": "string"
},
{
- "name": "scientificname",
- "in": "query",
- "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
- "required": false,
+ "name": "siteCode",
+ "in": "path",
+ "description": "Site to check for files",
+ "required": true,
"type": "string"
},
{
- "name": "verbose",
- "in": "query",
- "description": "Get verbose result set",
- "required": false,
- "type": "boolean"
- },
- {
- "name": "offset",
- "in": "query",
- "description": "The number of items to skip before starting to collect the result set",
- "required": false,
- "type": "integer"
- },
- {
- "name": "limit",
- "in": "query",
- "description": "The number of items to limit the result set to",
- "required": false,
- "type": "integer"
+ "name": "year-month",
+ "in": "path",
+ "description": "YYYY-MM month to check for files",
+ "required": true,
+ "type": "string"
},
{
- "name": "stream",
+ "name": "package",
"in": "query",
- "description": "Option to obtain the result as a stream. Utilize for large requests.",
+ "description": "Package type to return, basic or expanded",
"required": false,
- "type": "boolean"
+ "type": "string",
+ "enum": [
+ "basic",
+ "expanded"
+ ]
}
],
"responses": {
"200": {
- "description": "List of taxonomic information",
- "schema": {
- "type": "object",
- "properties": {
- "count": {
- "type": "integer",
- "description": "The number of results in the current paged response"
- },
- "total": {
- "type": "integer",
- "description": "The total number of results for the query"
- },
- "prev": {
- "type": "string",
- "format": "uri",
- "description": "Link to the previous page of results when available"
- },
- "next": {
+ "description": "Available data package as zip",
+ "content": {
+ "application/zip": {
+ "schema": {
"type": "string",
- "format": "uri",
- "description": "Link to the next page of results when available"
- },
- "data": {
- "type": "array",
- "items": {
- "$ref": "#/definitions/taxonomy"
- }
+ "format": "binary"
}
}
}
},
"400": {
- "description": "Taxonomic data does not exist for specified query",
+ "description": "Invalid product, site, or month specified",
"schema": {
"type": "object",
"properties": {
@@ -1760,6 +1588,178 @@
}
}
},
+ "/taxonomy": {
+ "get": {
+ "description": "Get taxonomic lists",
+ "tags": [
+ "Taxonomy"
+ ],
+ "operationId": "Get_taxonomy",
+ "produces": [
+ "application/json"
+ ],
+ "parameters": [
+ {
+ "name": "taxonTypeCode",
+ "in": "query",
+ "description": "Taxon type code to get. Must not be used in conjunction with a taxon rank query parameter.",
+ "required": false,
+ "enum": [
+ "ALGAE",
+ "BEETLE",
+ "BIRD",
+ "FISH",
+ "HERPETOLOGY",
+ "MACROINVERTEBRATE",
+ "MOSQUITO",
+ "MOSQUITO_PATHOGENS",
+ "SMALL_MAMMAL",
+ "PLANT",
+ "TICK"
+ ],
+ "type": "string"
+ },
+ {
+ "name": "kingdom",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "phylum",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "division",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "order",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "class",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "family",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "genus",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "scientificname",
+ "in": "query",
+ "description": "The taxon rank to get. Must not be used in conjunction with taxon type code.",
+ "required": false,
+ "type": "string"
+ },
+ {
+ "name": "verbose",
+ "in": "query",
+ "description": "Get verbose result set",
+ "required": false,
+ "type": "boolean"
+ },
+ {
+ "name": "offset",
+ "in": "query",
+ "description": "The number of items to skip before starting to collect the result set",
+ "required": false,
+ "type": "integer"
+ },
+ {
+ "name": "limit",
+ "in": "query",
+ "description": "The number of items to limit the result set to",
+ "required": false,
+ "type": "integer"
+ },
+ {
+ "name": "stream",
+ "in": "query",
+ "description": "Option to obtain the result as a stream. Utilize for large requests.",
+ "required": false,
+ "type": "boolean"
+ }
+ ],
+ "responses": {
+ "200": {
+ "description": "List of taxonomic information",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "count": {
+ "type": "integer",
+ "description": "The number of results in the current paged response"
+ },
+ "total": {
+ "type": "integer",
+ "description": "The total number of results for the query"
+ },
+ "prev": {
+ "type": "string",
+ "format": "uri",
+ "description": "Link to the previous page of results when available"
+ },
+ "next": {
+ "type": "string",
+ "format": "uri",
+ "description": "Link to the next page of results when available"
+ },
+ "data": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/taxonomy"
+ }
+ }
+ }
+ }
+ },
+ "400": {
+ "description": "Taxonomic data does not exist for specified query",
+ "schema": {
+ "type": "object",
+ "properties": {
+ "errors": {
+ "type": "array",
+ "items": {
+ "$ref": "#/definitions/error"
+ }
+ }
+ }
+ }
+ },
+ "default": {
+ "description": "General error",
+ "schema": {
+ "$ref": "#/definitions/error"
+ }
+ }
+ }
+ }
+ },
"/prototype/datasets": {
"get": {
"description": "Get information about all prototype datasets",