Using the Client with the OpenET Geodatabase API

The geodatabase API is supported, including functions that allow pulling ET data for spatial objects.

import os
import geopandas
import openet_client

features = "PATH TO YOUR SPATIAL DATA" # must be a format geopandas supports, which is most spatial data
df = geopandas.read_file(features)

client = openet_client.OpenETClient()
client.token = os.environ["OPENET_TOKEN"]
result = client.geodatabase.get_et_for_features(params={
        "aggregation": "mean",
        "feature_collection_name": "CA",
        "model": "ensemble_mean",
        "variable": "et",
        "start_date": 2018,
        "end_date": 2018
    },
    features=df,
    feature_type=openet_client.geodatabase.FEATURE_TYPE_GEOPANDAS,
    output_field="et_2018_mean_ensemble_mean",
    endpoint="timeseries/features/stats/annual"
)

More documentation for this portion of the API will be forthcoming, but note that, like the raster API, you provide a set of parameters that will be sent directly to OpenET based on the endpoint. The function get_et_for_features takes many additional parameters that indicate what kind of data you’re providing as an input, in this case a geopandas data frame. You also can provide different geodatabase feature endpoints.

This function then calculates the centroid of each feature, finds the fields in OpenET that are associated with those centroids, then downloads the ET data for those fields based on the params you provide. It attaches the ET to a data frame as a new field with the name specified in output_field. Note that for large features, it does not currently retrieve ET for multiple fields and aggregate them to the larger area. For that functionality, use the raster functionality.

This function also caches the field IDs for the features to avoid future lookups that use API quota. Rerunning the same features with different params will run significantly faster and use significantly fewer API requests behind the scenes.

Geodatabase API Access Class and Methods

class openet_client.Geodatabase(client)
feature_ids_list(params=None)

The base OpenET Method - sends the supplied params to metadata/openet/region_of_interest/feature_ids_list and returns the requests.Response object

Parameters:

params –

Returns:

get_et_for_features(params, features, feature_type, output_field=None, geometry_field='geometry', endpoint='timeseries/features/stats/annual', wait_time=5000, batch_size=40, return_type='joined', join_type='outer')

Takes one of multiple data formats (user specified, we’re not inspecting it - options are geopandas, geojson) and gets its coordinate values, then gets the field IDs in OpenET for the coordinate pair, retrieves the ET data and returns it as a geopandas data frame with the results in the specified output_field

Parameters:

  • params –

  • features –

  • endpoint – which features endpoint should it use?

  • return_type –

    How should we return the data? Options are “raw” to return just the JSON from OpenET, “list” to return a list of dictionaries with the OpenET data, “pandas” to return a pandas

    data frame of the results, or “joined” to return the

    data joined back to the input data. “joined” is the default.

  • join_type – When merging results back in, what type of join should we use? Defaults to “outer” so that records are retained even if no results come back for them. This is also useful behavior when we have multiple timeseries records, such as for monthly results, but it can duplicate input records (not always desirable). To change the behavior, change this to any value supported by pandas.merge or change the return_type so no join occurs.

Returns:

get_et_for_openet_feature_list(feature_ids, endpoint, params, wait_time=5000, batch_size=40)

Retrieve ET for a list of OpenET Feature IDs and return the raw JSON data. To handle retrieving for spatial data you already have, use get_et_for_features instead.

Parameters:

  • feature_ids – a list of strings containing OpenET feature IDs

  • endpoint – The OpenET endpoint to run the request against. No default

  • params – The parameters as specified in the OpenET documentation (https://open-et.github.io)

  • wait_time – How long to wait between requests to avoid hitting a rate limit. Defaults to 5 seconds

  • batch_size – How large of batches should we use by default? Defaults to 40

Returns:

A list of dictionaries as returned from JSON by the OpenET API

get_feature_ids(features, field=None, wait_time=5000)

An internal method used to get a list of coordinate pairs and return the feature ID. Values come back as a dictionary where the input item in the list (coordinate pair shown as DD Longitude space DD latitude) is a dictionary key and the value is the OpenET featureID

Parameters:

  • features –

  • field – when field is defined, features will be a pandas data frame with a field that has the coordinate values to use. In that case, results will be joined back to the data frame as the field openet_feature_id.

  • wait_time – how long in ms should we wait between subsequent requests?

Returns: