API Documentation

Complete reference for the PerilPulse API. Get property-level hazard risk data with simple REST calls.

rocket_launch Introduction

The PerilPulse API provides comprehensive property-level hazard risk data for every address in the United States. Our RESTful API returns risk scores and grades for 25+ hazard types, enabling instant underwriting decisions and accurate risk assessment.

Key Features

  • • RESTful API design
  • • Sub-100ms response times
  • • Letter grades (A-F) for all hazards
  • • Detailed risk parameters
  • • 99.9% uptime SLA

HazardHub Compatible

  • • Drop-in replacement API
  • • Same endpoint structure
  • • Identical response format
  • • Zero code changes needed
  • • Better pricing model

key Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

HTTP Header
Authorization: Token token=YOUR_API_KEY

Security Note: Keep your API key secure. Never expose it in client-side code or public repositories.

flash_on Quick Start

Get started in 3 simple steps:

1

Get your API key

Sign up at app.perilpulse.com and grab your API key from the dashboard.

2

Make your first request

bash
curl -H "Authorization: Token token=YOUR_API_KEY" \
  "https://api.perilpulse.com/v1/risks?address=123+Main+St&city=Austin&state=TX&zip=78701"
3

Get instant results

Receive comprehensive risk data in under 100ms.

link Base URL

All API requests should be made to:

URL
https://api.perilpulse.com/v1

Available Formats

  • • JSON (default)
  • • YAML (coming soon) - add ?format=yaml

Protocol

  • • HTTPS only
  • • TLS 1.2+ required

assessment Risk Assessment

GET /risks

Returns comprehensive hazard risk scores and grades for a specific property location.

Request Parameters

Parameter Type Required Description
lat number Yes* Latitude (-90 to 90)
lng number Yes* Longitude (-180 to 180)
address string Yes* Street address
city string No City name
state string No State code (e.g., TX)
zip string No ZIP code
unit string No Unit/apartment number

* Either lat/lng OR address is required

Example Request

HTTP Request
GET /v1/risks?address=123+Main+St&city=Austin&state=TX&zip=78701
Authorization: Token token=YOUR_API_KEY

Example Response

JSON Response
{
  "address": "123 Main St, Austin, TX, 78701",
  "lat": 30.2672,
  "lng": -97.7431,
  "wildfire": {
    "score": "B",
    "text": "Low"
  },
  "flood": {
    "score": "A",
    "text": "None/Very Low"
  },
  "earthquake": {
    "score": "A",
    "text": "Very Low"
  }
  // ... more hazards
}

home Enhanced Property Data Coming Soon

GET /enhanced_property_data

Returns detailed property characteristics including ownership, assessment values, and building details.

Request Parameters

Same as the /risks endpoint - use either lat/lng or address-based parameters.

Example Response

JSON Response
{
  "property": {
    "address": "123 MAIN ST, AUSTIN, TX 78701",
    "apn": "123-456-789",
    "owner": "JOHN DOE",
    "use_code": "Single Family Residential",
    "zip": "78701"
  },
  "assessment": {
    "Assessed_Improvement_Value": 250000,
    "Assessed_Land_Value": 150000,
    "Assessment_Year": "2023",
    "Building_Area": 2500,
    "Number_of_Bedrooms": 3,
    "Number_of_Baths": 2,
    "Year_Built": "1985",
    "Total_Assessed_Value": 400000
  },
  "mortgage_info": {
    "Current_Est_LTV_Combined": "75.5",
    "Total_Open_Lien_Balance": "300000"
  },
  "valuation": {
    "price_range_max": 450000,
    "price_range_min": 380000
  }
}

attach_money Replacement Cost Data Coming Soon

🚧 Under Development: The replacement cost endpoint is currently being developed and will be available soon. This endpoint will provide estimated replacement costs for residential and commercial properties.

GET /replacement_cost_data

Will return estimated replacement cost for residential and commercial properties.

Request Parameters

Parameter Type Required Description
Standard location parameters (same as /risks)
land_use_category string No "commercial" or "residential"
structure_type string No Building type (e.g., "Apartment", "Office")
square_footage number No Total floor area
number_of_stories number No Number of floors
year_built number No Year constructed
construction_type string No Construction material type

Example Response

JSON Response
{
  "replacement_cost": "578000.00",
  "architectural_style": "Colonial",
  "construction_quality": "average / standard",
  "construction_type": "framing, wood",
  "primary_exterior": "vinyl siding",
  "primary_roof_covering": "asphalt shingle",
  "number_of_stories": "2",
  "living_area": {
    "year_built": "1985",
    "square_footage": "2500"
  },
  "FinalRCVInclusiveOfDebrisRemoval": "607000.00",
  "DebrisRemoval": "29000.00",
  "BreakdownOfReplacementCost": {
    "ArchtectFeesAndPermits": "58000.00",
    "HouseMaterialsAndLabor": "404000.00",
    "Overhead": "58000.00",
    "Profit": "58000.00"
  }
}

merge_type Combined Data Endpoints Coming Soon

🚧 Under Development: Combined data endpoints are currently being developed to provide multiple data types in a single request. These endpoints will significantly improve efficiency by reducing the number of API calls needed.

For efficiency, we will offer combined endpoints that return multiple data types in a single request:

GET /risks_and_enhanced_property Coming Soon

Will return both risk assessment and enhanced property data in one call.

JSON Response
{
  "risks": { /* risk data */ },
  "enhanced_property": { /* property data */ }
}
GET /risks_and_enhanced_property_and_replacement_cost_data Coming Soon

Will return risks, property data, and replacement cost in one comprehensive response.

JSON Response
{
  "risks": { /* risk data */ },
  "enhanced_property": { /* property data */ },
  "replacement_cost_data": { /* replacement cost */ }
}

schema Response Structure

Standard Risk Response

Each hazard in the response contains:

Core Fields

  • score - Letter grade (A-F)
  • text - Risk description
  • Additional hazard-specific parameters

Risk Grades

  • A - Very Low Risk
  • B - Low Risk
  • C - Moderate Risk
  • D - High Risk
  • F - Very High Risk

analytics Risk Score Details

Each hazard type includes specific parameters and scoring methodology:

Wildfire Risk

  • • Vegetation density and type
  • • Historical fire perimeters
  • • Seasonal wind patterns
  • • Distance to fire stations
  • • Fire suppression capabilities

Flood Risk

  • • FEMA flood zones
  • • Distance to water bodies
  • • Elevation analysis
  • • Storm surge potential
  • • Historical claim data

Additional Hazards

  • • Earthquake, Hurricane, Tornado
  • • Hail, Wind, Lightning
  • • Crime, Environmental risks
  • • And 15+ more hazard types

error_outline Error Handling

Error Response Format

JSON
{
  "errors": "Description of the error"
}

Common Error Scenarios

Invalid coordinates: {"errors": "Lat must be less than or equal to 90"}
Address not found: {"errors": "Address can not be geocoded"}
Invalid API key: {"errors": "Bad credentials"}

flag HTTP Status Codes

200
Success - Request completed successfully
400
Bad Request - Invalid parameters or malformed request
401
Unauthorized - Invalid or missing API key
403
Forbidden - Rate limit exceeded (5-minute window)
404
Not Found - Address cannot be geocoded or endpoint doesn't exist
429
Too Many Requests - Account rate limit exceeded

code Code Examples

cURL

bash
# Basic risk assessment
curl -X GET \
  'https://api.perilpulse.com/v1/risks?address=123+Main+St&city=Austin&state=TX&zip=78701' \
  -H 'Authorization: Token token=YOUR_API_KEY'

# Using coordinates
curl -X GET \
  'https://api.perilpulse.com/v1/risks?lat=30.2672&lng=-97.7431' \
  -H 'Authorization: Token token=YOUR_API_KEY'

# Combined endpoint
curl -X GET \
  'https://api.perilpulse.com/v1/risks_and_enhanced_property?address=123+Main+St&city=Austin&state=TX' \
  -H 'Authorization: Token token=YOUR_API_KEY'

Python

python
import requests

# Configuration
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.perilpulse.com/v1"
headers = {"Authorization": f"Token token={API_KEY}"}

# Risk assessment
def get_risk_assessment(address, city, state, zip_code):
    params = {
        "address": address,
        "city": city,
        "state": state,
        "zip": zip_code
    }
    response = requests.get(f"{BASE_URL}/risks", headers=headers, params=params)
    return response.json()

# Enhanced property data
def get_property_data(lat, lng):
    params = {"lat": lat, "lng": lng}
    response = requests.get(f"{BASE_URL}/enhanced_property_data", headers=headers, params=params)
    return response.json()

# Example usage
risk_data = get_risk_assessment("123 Main St", "Austin", "TX", "78701")
print(f"Wildfire Risk: {risk_data['wildfire']['score']}")
print(f"Flood Risk: {risk_data['flood']['score']}")

JavaScript

javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.perilpulse.com/v1';

// Risk assessment function
async function getRiskAssessment(address, city, state, zip) {
    const params = new URLSearchParams({
        address: address,
        city: city,
        state: state,
        zip: zip
    });
    
    try {
        const response = await fetch(`${BASE_URL}/risks?${params}`, {
            headers: {
                'Authorization': `Token token=${API_KEY}`
            }
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        return await response.json();
    } catch (error) {
        console.error('Error fetching risk data:', error);
        throw error;
    }
}

// Combined data function
async function getCombinedData(address, city, state) {
    const params = new URLSearchParams({ address, city, state });
    
    const response = await fetch(
        `${BASE_URL}/risks_and_enhanced_property_and_replacement_cost_data?${params}`,
        {
            headers: { 'Authorization': `Token token=${API_KEY}` }
        }
    );
    
    return response.json();
}

// Example usage
getRiskAssessment('123 Main St', 'Austin', 'TX', '78701')
    .then(data => {
        console.log('Risk Assessment:', data);
        console.log('Wildfire Score:', data.wildfire.score);
        console.log('Flood Score:', data.flood.score);
    })
    .catch(error => console.error('Error:', error));

PHP

php
<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.perilpulse.com/v1';

// Risk assessment function
function getRiskAssessment($address, $city, $state, $zip) {
    global $apiKey, $baseUrl;
    
    $params = http_build_query([
        'address' => $address,
        'city' => $city,
        'state' => $state,
        'zip' => $zip
    ]);
    
    $options = [
        'http' => [
            'header' => "Authorization: Token token=$apiKey\r\n",
            'method' => 'GET'
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents("$baseUrl/risks?$params", false, $context);
    
    return json_decode($result, true);
}

// Enhanced property with curl
function getPropertyData($lat, $lng) {
    global $apiKey, $baseUrl;
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, "$baseUrl/enhanced_property_data?lat=$lat&lng=$lng");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Token token=$apiKey"
    ]);
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Example usage
$riskData = getRiskAssessment('123 Main St', 'Austin', 'TX', '78701');
echo "Wildfire Risk: " . $riskData['wildfire']['score'] . "\n";
echo "Flood Risk: " . $riskData['flood']['score'] . "\n";
?>

RiskObjects - Underwriters Technologies

xojo
// Create a new URLConnection
Dim connection As New URLConnection

// Set the API endpoint
Dim url As String = "https://api.perilpulse.com/v1/risks"

// Build query parameters
Dim params() As String
params.Add("address=123 Main St")
params.Add("city=Austin")
params.Add("state=TX")
params.Add("zip=78701")

// Combine URL with parameters
url = url + "?" + Join(params, "&")

// Set authorization header
connection.RequestHeader("Authorization") = "Token token=YOUR_API_KEY"

// Make the request
Dim response As String
Try
  response = connection.SendSync("GET", url)
  
  // Parse JSON response
  Dim json As New JSONItem(response)
  
  // Create RiskObject
  Dim riskObj As New RiskObject
  riskObj.Address = json.Value("address")
  riskObj.Latitude = json.Value("lat")
  riskObj.Longitude = json.Value("lng")
  
  // Parse hazard scores
  Dim wildfire As JSONItem = json.Child("wildfire")
  riskObj.WildfireScore = wildfire.Value("score")
  riskObj.WildfireText = wildfire.Value("text")
  
  Dim flood As JSONItem = json.Child("fema_all_flood")
  riskObj.FloodScore = flood.Value("score")
  riskObj.FloodText = flood.Value("text")
  
  Dim earthquake As JSONItem = json.Child("earthquake")
  riskObj.EarthquakeScore = earthquake.Value("score")
  riskObj.EarthquakeText = earthquake.Value("text")
  
  // Fire protection details
  Dim fireProtection As JSONItem = json.Child("fire_protection")
  riskObj.FireProtectionScore = fireProtection.Value("score")
  riskObj.FireProtectionText = fireProtection.Value("text")
  
  // Distance to coast
  Dim coastDistance As JSONItem = json.Child("coast_distance")
  riskObj.CoastDistance = coastDistance.Value("distance")
  riskObj.CoastDistanceUnits = coastDistance.Value("units")
  
  // Continue for other hazards...
  
  // Display results
  MsgBox("Property Risk Assessment for: " + riskObj.Address + EndOfLine + _
         "Wildfire Risk: " + riskObj.WildfireScore + " - " + riskObj.WildfireText + EndOfLine + _
         "Flood Risk: " + riskObj.FloodScore + " - " + riskObj.FloodText)
  
Catch error As RuntimeException
  MsgBox("Error: " + error.Message)
End Try

RiskObjects is a native object-oriented framework for accessing PerilPulse data in desktop applications. Developed by Underwriters Technologies for seamless integration.

speed Rate Limits

Default Limits

  • • 10 requests per second
  • • 10,000 requests per day
  • • Burst allowance for spikes
  • • 5-minute rate limit window

Rate Limit Headers

  • X-RateLimit-Limit - Request limit
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Reset timestamp

Need higher limits? Contact us for enterprise rate limits tailored to your needs.

warning Available Hazard Types

Our API provides risk assessments for 25+ hazard types, each with letter grades and detailed parameters:

Natural Disasters

  • • Wildfire
  • • Flood (FEMA)
  • • Earthquake
  • • Hurricane
  • • Tornado
  • • Tsunami
  • • Volcano
  • • Landslide

Weather Risks

  • • Hail
  • • Wind
  • • Lightning
  • • Ice Dam
  • • Frozen Pipes
  • • Snow Load
  • • Drought
  • • Heat Index

Other Risks

  • • Crime
  • • Radon
  • • Sinkhole
  • • Mine Subsidence
  • • Superfund Sites
  • • Underground Storage
  • • Sea Level Rise
  • • Airport Noise

swap_horiz Migration from HazardHub

Switching from HazardHub? It's easier than you think:

1

Update Base URL

Change from api.hazardhub.com to api.perilpulse.com

2

Update API Key

Replace your HazardHub API key with your new PerilPulse key

3

That's it!

Same endpoints, same response format, better pricing

Pro tip: Our API is 100% compatible with HazardHub's JSON schema. No need to change your data models or parsing logic.

help Support

Technical Support

Additional Resources