DEVISE API
How to query DEVISE data
Base GET requests
DEVISE API is a RESTful API (An API with pre-formatted data querying and filtering options). The public facing services include 3 base GET options which are listed here:
| GET | Description |
|---|---|
| devise.uwyo.edu/GetS3Urls | Get S3 urls - retrieves an array of all .tif dataset url files and the associated parameter constraints |
| devise.uwyo.edu/Variables | Get variables - retrieves an array of information containing all combinations of available parameters |
| devise.uwyo.edu/Timescale | Get timescale - retrieves an array of available timescales for each dataset |
Each GET request returns an array of JSON objects with the following object formats
S3 object format
| Property | Description | Type |
|---|---|---|
| url | Full .tif file path | string |
| filename | .tif file name | string |
| resolution | geographic tile size | string |
| timescale | The unit time incrementation (how often is the variable collected or aggregated) | string |
| variable | The quantitified value abbreviated | string |
| startyear | First year in data | string |
| sampMonth | month of interest in this object (across all years) | string |
| scale | Cell value conversion factor to preserve decimal digits | double (number) |
| units | variable measurement | string |
| alias | Full variable name | string |
| statistics | Raster summary statistics (min, max, sd, mean) Double check | string |
Variable object format
| Property | Description | Type |
|---|---|---|
| dataset | The raw data collection source | string |
| variable | The quantitified value abbreviated | string |
| alias | Full variable name | string |
| units | The variable measurement amount | string |
| englishUnits | The alternative english measurement amount | string |
| description | Description of this object’s data (all rows summarized) | string |
| scaleFactor | Cell value conversion factor to preserve decimal digits | double (number |
| aggregationFunction | Monthly data aggregation formula for an annual basis | string |
Timescale object format
| Property | Description | Type |
|---|---|---|
| timescale | The unit time incrementation (how often is the variable collected or aggregated) | string |
| dataset | The raw data collection source | string |
To understand the types of variables, datasets, resolutions, and properties see the Overview section of the documentation.
Key to filtering GET array objects
The 3 base GET requests can be modified for more specific JSON object selection by specifying which parameters the user is interested in. (Note: Some parameter combinations may result in errors, so be sure to read the the filtering options thoroughly before modifying your own. Additionally, users wishing to access data may generate and test their requests through our Swagger page)
/GetS3Urls GET filtering options
The S3 GET has six additional filter parameters.
Parameter Information
| Parameter | Request URL extension example | Type |
|---|---|---|
| Variable | Variable=prcp | string |
| Dataset | Dataset=daymet | string |
| Timescale | Timescale=daily | string |
| Startyear (or year of interest) | Startyear=2004&Startyear=2005 | array<string> |
| Sampmonth (or month of interest) | Sampmonth=1&Sampmonth=2 | array<string> |
| Resolution | Resolution=1%20km | string |
Filtering objects with some array<string> parameter types will not be compatible with all Timescale selections.
When filtering for specific Startyears users are expected to select a daily timescale otherwise the request will default to all years. (EX: Timescale=daily&Startyear=2004&Startyear=2005 will return two objects for every variable and dataset, one with a tif url accessing daily data from 2004 and the other containing daily data from 2005)
When filtering for a specific sampmonth users are expected to select a monthly Timescale (EX: Timescale=monthly&Sampmonth=1&Sampmonth=2 will return the object with a tif file containing data from the months of January and February across every year in the dataset)
/Variables GET filtering options
The variable GET has one additional filtering parameter.
Parameter Information
| Parameter | Request URL extension example | Type |
|---|---|---|
| dataset | dataset=daymet | string |
/Timescale GET filtering options
The timescale GET has one additional filtering parameter.
Parameter Information
| Parameter | Request URL extension example | Type |
|---|---|---|
| dataset | dataset=daymet | string |
Example /GetS3Urls Queries
Get all S3 urls
https://devise.uwyo.edu/GetS3Urls
Returns every combination of dataset urls and parameters
Output
Get all S3 urls with a specified variable
https://devise.uwyo.edu/GetS3Urls?Variable=prcp
Returns every combination of dataset urls and parameters with the parameter, variable, set to Daymet precipitation (prcp). (Note: The dataset PRISM also contains a precipitation variable ppt)
Output
Get all S3 urls with several specified parameters
Returns three JSON objects with the precipitation variable from dataset Daymet. The first object url contains all daily 2003 values, the second object url contains all daily 2005 values, and the third value contains all daily 2004 values.
Output
Example /Variables queries
Get all available datasets variables
https://devise.uwyo.edu/Variables?dataset=daymet
Returns an array of lists with all the Daymet dataset variable combinations.
Output
Example /Timescale queries
Get all Dataset timescales
https://devise.uwyo.edu/Timescale
Output
Get a specific Dataset’s timescales
https://devise.uwyo.edu/Timescale?dataset=daymet
Retrieve the timescales for a specific dataset
Output