Client Usage

Installation

Get the latest version of the client python script from the GitHub repository and put the intensel_api_client.py file in your project directory.

Usage

The client script is a simple Python script that can be used to interact with the Intensel API. The script can be used to make API requests to the Intensel API and retrieve the response.

Here is quick example of how to use the client script to make an API request to the Intensel API:

1. First, import the library and create a client instance:

   from intensel_api_client import IntenselAPIClient, AnalysisType, OutputFormat
   
   client = IntenselAPIClient('YOUR_API_KEY')
   info

   Make sure to replace 'YOUR_API_KEY' with your actual Intensel API key.

2. Now, let's create a project and add an asset:

   # Create a new project
   project_name = "My First Intensel Project"
   client.create_project(project_name=project_name, variables=["rainfall_flood", "extreme_heat"])
   
   # Add an asset to the project
   asset_data = {
       "name": "Downtown Office Building",
       "latitude": 22.2838,
       "longitude": 114.1588,
       "area": 5000,
       "valuation": 10000000,
       "stories": 20
   }
   client.add_single_asset(project_name=project_name, asset_data=asset_data)

3. Great! Now let's retrieve some hazard data for our project:

   hazard_data = client.get_project_data(
       data_type="hazard",
       project_name=project_name,
       analysis_type=AnalysisType.RCP,
       variables=["rainfall_flood", "extreme_heat"],
       scenarios=["0.0", "2.6", "4.5", "8.5"],
       years=["2020", "2030", "2050"]
   )
   
   print(hazard_data)

Supported parameters

Variables

• river_flood
• typhoon
• storm_surge
• landslide
• extreme_heat
• snow_melt
• rainfall_flood
• drought
• sea_level_rise
• wild_fire

Analysis Types

• AnalysisType.RCP: Representative Concentration Pathways (RCP) analysis.
• AnalysisType.SSP: Shared Socioeconomic Pathways (SSP) analysis.

Scenarios

RCP/SSP scenarios for hazard data:

• 0.0: Baseline scenario.
• 2.6: Low emissions scenario.
• 4.5: Medium-low emissions scenario.
• 8.5: High emissions scenario.

Years

• For RCP analysis: 2020, 2030, 2050
• For SSP analysis: 2020, 2030, 2050, 2100

Output Formats

• OutputFormat.JSON: JSON format (default).
• OutputFormat.CSV: CSV format.
• OutputFormat.EXCEL: Excel format.
• OutputFormat.HTML: HTML format.

Analysis Data Types

• hazard: Climate hazard data.
• loss: Asset loss data.
• scores: Risk scores.

Examples

Let's walk through a few more examples to show you how to use the Intensel API Client Library in real-world scenarios.

Analyzing Multiple Assets Across Different Time Periods

from intensel_api_client import IntenselAPIClient, AnalysisType, OutputFormat

client = IntenselAPIClient('YOUR_API_KEY')

# Create a project for analyzing urban heat islands
project_name = "Urban Heat Island Study"
client.create_project(project_name=project_name, variables=["extreme_heat", "rainfall_flood"])

# Add multiple assets representing different city areas
assets = [
    {"name": "Downtown", "latitude": 40.7128, "longitude": -74.0060},
    {"name": "Suburban Park", "latitude": 40.7282, "longitude": -73.7949},
    {"name": "Industrial Zone", "latitude": 40.6782, "longitude": -73.9442}
]
client.add_bulk_assets(project_name=project_name, asset_data_list=assets)

# Retrieve hazard data for multiple time periods
hazard_data = client.get_project_data(
    data_type="hazard",
    project_name=project_name,
    analysis_type=AnalysisType.RCP,
    variables=["extreme_heat", "rainfall_flood"],
    scenarios=["2.6", "8.5"],
    years=["2030", "2050"]
)

print(hazard_data)

Comparing Different Climate Scenarios

from intensel_api_client import IntenselAPIClient, AnalysisType, OutputFormat

client = IntenselAPIClient('YOUR_API_KEY')

# Create a project for coastal flood risk assessment
project_name = "Coastal Flood Risk Assessment"
client.create_project(project_name=project_name, variables=["sea_level_rise", "storm_surge"])

# Add a coastal property
asset = {
    "name": "Oceanfront Resort",
    "latitude": 25.7617,
    "longitude": -80.1918,
    "area": 20000,
    "valuation": 100000000,
    "stories": 20
}
client.add_single_asset(project_name=project_name, asset_data=asset)

# Retrieve loss data for different scenarios
loss_data = client.get_project_data(
    data_type="loss",
    project_name=project_name,
    analysis_type=AnalysisType.SSP,
    variables=["sea_level_rise", "storm_surge"],
    scenarios=["2.6", "4.5", "8.5"],
    years=["2050", "2100"]
)

print(loss_data)

API Reference

Now, let's take a detailed look at each method in the IntenselAPIClient class.

IntenselAPIClient(api_key: str)

This is the main class you'll be using to interact with the Intensel API.

Parameters:

• api_key (str): Your Intensel API key.

Example:

client = IntenselAPIClient('YOUR_API_KEY')

create_project(project_name: str, variables: List[str]) -> Dict

Creates a new project in your Intensel account.

Parameters:

• project_name (str): The name of your project.
• variables (List[str]): A list of climate variables you want to analyze in this project.

Returns: A dictionary containing the API response.

Example:

response = client.create_project("Coastal Properties", ["sea_level_rise", "storm_surge"])

add_single_asset(project_name: str, asset_data: Dict) -> Dict

Adds a single asset to an existing project.

Parameters:

• project_name (str): The name of the project to add the asset to.
• asset_data (Dict): A dictionary containing the asset's details.

Returns: A dictionary containing the API response.

Example:

asset = {
    "name": "Beachfront Hotel",
    "latitude": 25.7617,
    "longitude": -80.1918,
    "area": 10000,
    "valuation": 50000000,
    "stories": 15
}
response = client.add_single_asset("Coastal Properties", asset)

add_bulk_assets(project_name: str, asset_data_list: List[Dict]) -> Dict

Adds multiple assets to an existing project in a single API call.

Parameters:

• project_name (str): The name of the project to add the assets to.
• asset_data_list (List[Dict]): A list of dictionaries, each containing an asset's details.

Returns: A dictionary containing the API response.

Example:

assets = [
    {
        "name": "Beachfront Hotel",
        "latitude": 25.7617,
        "longitude": -80.1918,
        "area": 10000,
        "valuation": 50000000,
        "stories": 15
    },
    {
        "name": "Seaside Restaurant",
        "latitude": 25.7616,
        "longitude": -80.1917,
        "area": 500,
        "valuation": 2000000,
        "stories": 1
    }
]
response = client.add_bulk_assets("Coastal Properties", assets)

get_project_data(data_type: str, project_name: str, analysis_type: AnalysisType, variables: List[str], scenarios: List[str], years: List[str], output_format: OutputFormat = OutputFormat.JSON) -> Union[Dict, str]

Retrieves project data (hazard, loss, or scores) based on the specified parameters.

Parameters:

• data_type (str): The type of data to retrieve. Must be "hazard", "loss", or "scores".
• project_name (str): The name of the project.
• analysis_type (AnalysisType): The type of analysis (RCP or SSP).
• variables (List[str]): The list of climate variables to include in the data.
• scenarios (List[str]): The list of scenarios to include in the data.
• years (List[str]): The list of years to include in the data.
• output_format (OutputFormat, optional): The desired output format. Defaults to JSON.

Returns: The project data, either as a dictionary (for JSON format) or a string (for other formats).

Example:

data = client.get_project_data(
    "hazard",
    "Coastal Properties",
    AnalysisType.RCP,
    ["sea_level_rise", "storm_surge"],
    ["0.0", "4.5", "8.5"],
    ["2030", "2050"],
    OutputFormat.CSV
)