Reask API Hazard Data for Parametrics

The scripts in this repository are made available for free under the ROA (Reask Open Analytics) offering to facilitate work with Reask’s hazard data for parametric insurance structuring and pricing. Any commercial use of Reask data requires a formal agreement with Reask. The use of these scripts is at your own risk, and Reask assumes no liability for any errors, inaccuracies, or potential issues that may arise from these scripts.

Note: You must have valid Reask API credentials to query the data. If you do not have credentials, please contact Reask for access. Be sure to enter your credentials in the API_Authentication.r file (or equivalent) before running the scripts.

Historical and Probabilistic Tropical Cyclone Data from the Reask API

Author: David Schmid, Global Head of Data Products at Reask
Email: [email protected]

This repository contains R scripts that retrieve location-level wind and track data via the Reask API, process the responses to extract event data and save the results in Excel, CSV and Parquet formats. The repository also contains an authentication file to be completed with your personal credentials, and a sample locations.csv file.

Quick Start:

• Clone or download this repo.
• Install R and RStudio.
• Open the project file .Rproj in RStudio.
• Open the API_Authentication.r script and enter your personal credentials.
• Open and run the script API_Master.r.

---

Overview

• API_Master.r:
  Master file to set the hazard parameters and run both the Metryc and DeepCyc queries.
• API_metryc_tcwinds_events.r:
  Retrieves historical data from the Reask API based on DeepCyc.
• API_deepcyc_tcwinds_events.r:
  Retrieves probabilistic data from the Reask API based on DeepCyc.
• API_Authentication.r:
  Authenticates with the Reask API using your credentials.
• locations.csv:
  A sample CSV file containing location data (id, lat, lon, and limit). Modify this file with your actual locations. lat and lon must be included, id and limit is not required.
• Output Files:
  The processed results and meta data are saved as Excel, CSV and Parquet files.
• API.Rproj:
  R project file to set your working directory.

---

Prerequisites

• R (version 3.6 or later recommended)
• Recommended IDE: RStudio
• Git (if you plan to clone or pull updates from the repository)

---

Installation / Setup

Follow these steps to set up the project on your machine:

1. Navigate to the Parent Directory for Cloning:

   • Windows Users:
     Open the Command Prompt and navigate to the folder where you want to store the repository. For example:

     cd "C:\Users\DavidSchmid\Documents\Reask\API"

   • Mac Users:
     Open the Terminal and navigate to the folder where you want to store the repository. For example:

     cd "/Users/yourusername/Documents/Reask/API"

2. Clone or Download the Repository:

   • Clone:
     Run the following command in your terminal:

     git clone https://github.com/reaskearth/parametrics.git

     This creates a new folder parametrics containing the repository.

   • Download:
     Alternatively, click the "Download ZIP" button on the GitHub repository page, unzip the folder, and move it to your desired location.

3. Open the Project in RStudio:

   The repository includes an .Rproj file. Open this file in RStudio, and it will automatically set your working directory to the repository root. This ensures that all relative paths work correctly.

4. Project Structure:

   Your repository should have a structure similar to:

   repository-root/
   ├── API_Master.r             # Master file to run
   ├── API_Authentication.r         # Authentication file
   ├── API_deepcyc_tcwinds_events.r # API query for DeepCyc
   ├── API_metryc_tcwinds_events.r  # API query for DeepCyc
   ├── locations.csv                # Sample locations file
   ├── API.Rproj                # RStudio project file
   ├── README.md                    # This file
   ├── results                      # A folder will be created to save results
   

5. Configure Your Environment:

   • Authentication:
     Open API_Authentication.R and replace the placeholder "username" and "password" with your actual API credentials.

   • Adjust Parameters:
     Open API_Master.r and review the User Input Parameterisation section. Adjust parameters such as wind speed units, terrain correction, averaging period, threshold and location file.

---

Running the Code

1. Open the Project:
   In RStudio, open the .Rproj file from the repository root. This automatically sets the working directory.

2. Run the Main Script:
   Execute the API_Master.r script to process the data. The script will:

   • Load location data from locations.csv
   • Authenticate with the API
   • Retrieve historical and probabilstic data for each location
   • Apply filtering and construct a pivot table
   • Save outputs as Excel, CSV and Parquet files

3. Further Process Output:
   The processed files will be saved in the results folder. Open them with your preferred software to process the results.

---

API Access and Authentication

• API Access:
  To use the Reask API, you must have the appropriate access rights.
  Refer to the API Swagger Documentation for a full list of parameters and further details.
  If access is restricted, contact your administrator or follow the necessary steps to obtain API credentials.

• Authentication File (API_Authentication.r):
  This file sends a POST request to the Reask token endpoint, retrieves an access token, and sets up the necessary headers. Make sure to update this file with your actual credentials.

---

Contributing

Feel free to fork the repository and submit pull requests if you have improvements or bug fixes. Please follow standard GitHub contribution guidelines. Important: Do not include your personal API credentials in your commits or pull requests. If you need to update the authentication file, use placeholder so that sensitive information is not exposed.

---

License

Include license information here if applicable.

---

By following these instructions, you should be able to run the code on your machine with minimal adjustments. The repository is organized to be generic - simply clone or download, update the credentials and parameters, and run the script.

---