Python Scripts
Scaling up your analysis with the Climate Engine API
Making API calls from python scripts allows you to integrate the the power of cloud computing with your existing workflows and automate iterative processes. Unlike the app, you can export time series for numerous areas of interest with a few lines of code.
Getting Set Up
First, at the top of your script you will want to import any packages you will need for making maps, charts, etc. The Climate Engine API itself doesn't require any packages to utilize. You will need two things to get set up to make API requests: 1) a root URL and 2) authorization key. Additionally, you can set your google bucket variable in this section.
Requesting Rasters
To request a raster, first you need to select the appropriate endpoint for you goals. To see all of the endpoint options, you can visit the API docs page. The example below is the anomaly endpoint which exports a map of anomalies to a Google Cloud Storage bucket. You will need to give the Climate Engine google service account (climate-engine-pro-gcp@climate-engine-pro.iam.gserviceaccount.com) the Storage Object Creator role in your bucket permissions. Then you will specify the export file name. After that you need to fill out a parameters dictionary for the API call. The docs will let you know what parameters are required for particular endpoints and the options for each. For the anomaly endpoint, the API requires you to select a dataset and variable of interest. Then you must select a temporal statistic to reduce over. Then you must select from one of three calculation choices. It will also require a start and end date, as well as a start and end year to build the historical for. Lastly, you need to supply a bounding box and export path to where to send the map file. When you have the parameters filled out, you can structure a request. Once the request is made by running the API request cell, it will provide a response letting you know the status.
To read the exported map file (tif) into your script, an option is the google.colab package. You will need to authenticate your account when running it and set the project id.
Utilizing gsutil, you can copy your map file from google cloud storage to local storage/colab files. Then you can open it using your geospatial package of choice and generate a map using it. The example below utilizes Matplotlib to generate a Land Surface Temperature Difference from Average map using the MODIS Terra 8-day anomaly tif requested previously. You can customize it with a color bar, title, etc. The map can be exported as a png for use in reports, presentations, etc.
Requesting Time Series
Similarly to requesting maps, the first step of requesting a time series is to select the correct endpoint. The example below is a native coordinates endpoint that generates a time series of values of the dataset variable and time period between a start and end date at a location. The coordinates of the point(s) must be included in the parameters, as well as an area reducer. When you have the parameters filled out, you can structure a request. Once the request is made by running the API request cell, it will provide a response letting you know the status.
The request results can be converted from the native JSON format to a data frame for analysis or can exported as a csv. Additionally, the data frame can be used for additional processing and creation of charts.
To create charts, you can utilize your plotting package of choice. The example below utilizes the Matplotlib package. You can customize it with x-, y- labels, title, etc. The chart can be exported as a png for use in reports, presentations, etc.
