Sust Global Python API Client

This document details how to use the sust-api-client python package to interact with Sust Global’s Climate Explorer API.

Much of this client is generated using OpenAPI:

• Current OpenAPI Spec

• OpenAPI Spec Documentation

More on our developer documentation can be found at:

• Sust Global Developer Center

Install the client

You can install the client using pip:

pip install sust-api-client

The current version of the client is 0.0.22.

Introduction

Initialize a client, providing your Climate Explorer API key and project name (API_KEY and PROJECT, respectively):

from sust.api import ClimateExplorerClient
cl = ClimateExplorerClient(API_KEY, PROJECT)

You can scan through the list of available portfolios in the specified project and associated status using the following:

for pf in cl.portfolios():
    print(pf['portfolio_name'], pf['status'])

The status could be one of No data available, Waiting on risk data generation or Risk data available. To submit a new portfolio for risk data generation, you need to assign it a name and provide asset locations associated with the portfolio as a CSV file. Kindly use the intake template format for this purpose, see the Quick Start Guide for a demo portfolio as well:

pf = cl.create_portfolio(PORTFOLIO_NAME)
with open('path_to_intake_portfolio_asset.csv', 'rb') as af:
    pf.import_assets_csv(af)

Once asset level risk data is generated for your portfolio, the portfolio’s status changes to Risk data available. This process can take up to 24 hours depending on the size of the portfolio.

Accessing Physical Risk Exposure

The following demonstrates how to access the physical risk exposure timeseries data filtered to a specific scenario, hazard and indicator, then load it into a pandas dataframe for further analysis. Each row in the dataframe maps to an asset from the previously-uploaded CSV:

import pandas as pd

ds = pf.physical_risk_exposure()
ts = ds.timeseries(ds.scenarios.get('ssp585'), ds.indicators.get('wildfire', 'unified_prob'))
df = pd.DataFrame(ts.to_dicts())

The Sust Global API supports several of the IPCC CMIP6 climate scenarios, including ssp126, ssp245 and ssp585).

It is common practice to filter timeseries data to specific indicators. The following table documents the available values. When filtering to a specific indicator, it is important to provide the corresponding hazard value as well. An example of this is available just above.

Hazard	Indicator
cyclone	prob
cyclone	obs_freq
wildfire	unified_prob
wildfire	obs_score
flood_potential	inland_flood_prob
flood_potential	obs_score
water_stress	spei_norm
water_stress	score
water_stress	unified_score
water_stress	obs_score
sea_level_rise	change
heatwave	freq
fundamental	precip
fundamental	extreme_precip
fundamental	temp

Summary and timeseries data may be filtered to a hazard. To accomplish this, simply provide a hazard name to the PhysicalRiskExposureDataset.hazards.get method.

Summary datasets can also be filtered by summary window. Sust Global provides summaries over the 5, 15 and 30 year windows. An example follows:

ds = pf.physical_risk_exposure()
sm = ds.summary(ds.windows.get(5), ds.hazards.get('wildfire'))
df = pd.DataFrame(sm.to_dicts())

These examples showcase how you can access risk exposure datasets and load them to dataframes as an entry point for exploration data analysis.

Additional information is available in the Sust Global Dev Center.

Exporting Physical Risk Exposure

The Physical Risk Exposure information retrieved with the client can be exported to a ZIP file by using the method below:

ds = portfolio.physical_risk_exposure()
ds.export_zip(file_name='AGE1.zip') #save to local directory
ds.export_zip(file_name='/foo/bar/AGE1.zip') #save to /foo/bar

Using the Search Method with Coordinates

Retrieving Physical Risk Exposure information can also be retrieved by passing geographic coordinates to the Search method.

geo_risk = client.search(latitude=47.09764797110564, longitude=-122.8242285597761)

For a detailed description of the output returned by the search method, visit the OpenAPI spec documentation.

Python API Reference

class sust.api.climate_explorer.ClimateExplorerClient

This class wraps all Climate Explorer API functionality into one simple to use interface.

__init__(api_key: str, project: str)

Parameters

• api_key – Climate Explorer API key

• project – Climate Explorer project name or ID

create_portfolio(portfolio_name: str) → Portfolio

Create a new Portfolio.

Parameters

portfolio_name – name provided to new Portfolio. Limited to alphanumeric characters, underscores and hyphens.

portfolio(portfolio_name) → Portfolio

Retrieve a single Portfolio.

Parameters

portfolio_name – name of Portfolio to retrieve

portfolios() → List[Portfolio]

Retrieve all Portfolio objects.

search(latitude, longitude)

Retrieve climate risk information associated with the given coordinates

Parameters

• latitude – latitude of the location

• longitude – longitude of the location

class sust.api.climate_explorer.Portfolio

assets() → AssetList

Fetch all assets contained within this Portfolio.

import_assets_csv(fileobj)

Import assets to the portfolio from an open file-like object containing CSV-formatted data. This action will replace the existing assets contained within the Portfolio and trigger generation of risk exposure data. Visit the Sust Global Developer Center for help building a valid input file.

Parameters

fileobj – file-like object open for binary reading (e.g. acces mode ‘rb’)

physical_risk_exposure() → PhysicalRiskExposureDataset

Fetch published dataset metadata pertaining to the Portfolio.

class sust.api.climate_explorer.AssetList

export_csv() → IO

Export assets as a CSV file. The returned file-like object contains the same content originally uploaded to the Portfolio. The file-like object contains binary data.

to_dicts() → List[dict]

Convert object to python dictionaries.

class sust.api.climate_explorer.PhysicalRiskExposureDataset

export_zip(file_name=None) → IO

Export this physical risk exposure dataset as a zip file. The returned object is a binary file-like object. If file name is provided, the output will be saved to that location.

param file_name

Optional. The path to the location to save the zip file. If not provided, it will default to the current working directory

Typical usage example:

ds1 = pf.physical_risk_exposure()

out1 = ds1.export_zip(file_name=’file.zip’) #save to local directory

ds2 = pf.physical_risk_exposure()

out2 = ds2.export_zip(file_name=’/foo/bar/file.zip’)

property hazards: HazardList

Get a list of hazards supported by this dataset.

property indicators: IndicatorList

Get a list of indicators supported by this dataset.

property measures: MeasureList

Get a list of measures supported by this dataset.

property scenarios: ScenarioList

Get a list of scenarios supported by this dataset.

summary(*filters: Any) → PhysicalRiskExposureSummary

Retrieve physical risk exposure summary data contained within this dataset. Filters may be provided to limit the data returned.

Parameters

filters – Limit data using the provided filters. Typically, one should use the other methods on this class to construct filters. For example, the scenarios attribute will yield a set of objects describing which scenarios are supported by the dataset. Each object may independently be passed as a filter here to limit the results to the chosen scenario.

timeseries(*filters: Any) → PhysicalRiskExposureTimeseries

Retrieve physical risk exposure timeseries data from the dataset. Filters may be provided to limit the data returned.

Parameters

filters – Limit data using the provided filters. Typically, one should use the other methods on this class to construct filters. For example, the scenarios attribute will yield a set of objects describing which scenarios are supported by the dataset. Each object may independently be passed as a filter here to limit the results to the chosen scenario.

property version

Retrieve this dataset’s version number

property windows: WindowList

Get a list of summary windows supported by this dataset.

class sust.api.climate_explorer.PhysicalRiskExposureTimeseries

to_dicts() → List[dict]

Convert object to python dictionaries.

class sust.api.climate_explorer.PhysicalRiskExposureSummary

to_dicts() → List[dict]

Convert object to python dictionaries.

class sust.api.climate_explorer.Scenario

Metadata object representing an actual hazard offered by a discrete dataset. This can also be used to filter requests for data. This class should always be instantiated by an instance of PhysicalRiskExposureDataset.

__init__(name)

class sust.api.climate_explorer.ScenarioList

__init__(items)

:meta private:”

get(k)

Fetch a specific item from the list

class sust.api.climate_explorer.Hazard

Metadata object representing an actual hazard offered by a discrete dataset. This can also be used to filter requests for data. This class should always be instantiated by an instance of PhysicalRiskExposureDataset.

__init__(name)

class sust.api.climate_explorer.HazardList

__init__(items)

:meta private:”

get(k)

Fetch a specific item from the list

class sust.api.climate_explorer.Indicator

Metadata object representing an actual hazard offered by a discrete dataset. This can also be used to filter requests for data. This class should always be instantiated by an instance of PhysicalRiskExposureDataset.

__init__(obj)

to_dict()

class sust.api.climate_explorer.IndicatorList

__init__(items)

:meta private:”

get(hazard, indicator)

Fetch a specific item from the list

to_dicts()

class sust.api.climate_explorer.Window

Metadata object representing an actual hazard offered by a discrete dataset. This can also be used to filter requests for data. This class should always be instantiated by an instance of PhysicalRiskExposureDataset.

__init__(name)

class sust.api.climate_explorer.WindowList

__init__(items)

:meta private:”

get(k)

Fetch a specific item from the list

class sust.api.climate_explorer.Measure

Metadata object representing an actual hazard offered by a discrete dataset. This can also be used to filter requests for data. This class should always be instantiated by an instance of PhysicalRiskExposureDataset.

__init__(name)

class sust.api.climate_explorer.MeasureList

__init__(items)

:meta private:”

get(k)

Fetch a specific item from the list