Introduction to the API
Introduction
The Climate Engine API allows access to the same great dataset catalog and analytical capabilities that are available through the Climate Engine app. While the app provides a great ease of use and visualization, the API allows for more customization and scaling in your analyses. There are numerous ways to interact with the Climate Engine API, but we typically guide users toward two primary methods: 1) Swagger Page and 2) Python Notebooks.
What is an API?
API stands for application programming interface. An API allows different types of software to communicate with each other. Using an API is critical for connecting systems that are otherwise unable to interact with each other.
A simple example of an API is giving voice commands to your phone (i.e through Siri) to find directions to a restaurant through Google maps. The Siri virtual assistant and Google maps are owned by two different companies and have two completely different development teams that use different coding languages. The two programs should not be able to talk to each other, but an API allows Siri to send commands to Google maps and pull up the results for the user.
For Climate Engine, the API acts as a bridge between Climate Engine and either Python Notebooks, or the Swagger Page. Using either of these interfaces will send commands to Climate Engine where they will be processed.
Endpoints are critical to understand in the larger API interface. An endpoint is one end in the communication channel between the two applications. An application will use an endpoint to process a function with either a ‘response’ or a ‘request.’ To correctly send a request or interpret a response, a strict protocol established by the API must be followed. All requests and responses are mediated through JSON (JavaScript Object Notation), and so the returned data will often need to be “parsed” into a format for analysis to be performed, a step which we demonstrate in tutorial notebooks.
What Endpoints are available?
The Endpoints available in the Climate Engine API are broken down into four categories: 1) Maps, 2) Timeseries, 3) Zonal Statistics, and 4) Probabilities.
The Maps endpoints are used to generate maps (and map statistics) of the datasets available in Climate Engine. There are three groups of Maps endpoints: 1) mapid, 2) export, and 3) metadata. Mapid endpoints are used to generate Earth Engine maps, and produce an Earth Engine map ID value that you can visualize. Export endpoints are used to generate a map and export it to a Google Cloud Storage bucket. Metadata endpoints return percentiles and statistics of map values.
The Timeseries endpoints are used to generate time series data for the datasets available in Climate Engine. There are three groups of Timeseries endpoints: 1) native, 2) interannual, and 3) regression. Native endpoints are used to generate ‘raw’ time series data over points/polygons/features for Climate Engine datasets. Interannual endpoints are used to generate a time series of yearly values of the dataset variable summarized over a season. Regression endpoints are used to perform regression analysis of the dataset variable summarized over a season.
The Zonal Statistics endpoints are used to generate statistics for Climate Engine datasets over different geometries. There are three groups of Zonal Statistics endpoints: 1) pixel count, 2) values, and 3) value. Pixel count endpoints produce statistics and time series statistics on the number of pixels in each drought category for polygons and custom assets. Values endpoints compute temporal statistics which are reduced over specified geometric features. Value endpoints return values for statistic datasets (no time dependence) over different specified geometries.
The Probabilities endpoints are used to generate statistics for Climate Engine datasets over different geometries. There are three groups of Probabilities endpoints: 1) exceedance probabilities, 2) exterior probabilities, and 3) interior probabilities. Exceedance probabilities endpoints produce the probability of a variable value to exceed a threshold at a location defined by a geometry. Exterior probabilities endpoints produce the probability of a variable value to lie outside of a lower and an upper threshold at a location defined by a geometry. Interior probabilities endpoints produce the probability of a variable value to lie inside of a lower and an upper threshold at a location defined by a geometry.
Additional Documentation
To see the endpoints, datasets, and variable available through the API in more detail visit the docs site.