API Documentation
Complete reference for the PerilPulse API. Get property-level hazard risk data with simple REST calls.
Developer Resources
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
Authentication
All API requests require authentication using an API key. Include your key in the Authorization header:
Authorization: Token token=YOUR_API_KEY
Security Note: Keep your API key secure. Never expose it in client-side code or public repositories.
Quick Start
Get started in 3 simple steps:
Get your API key
Sign up at app.perilpulse.com and grab your API key from the dashboard.
Make your first request
curl -H "Authorization: Token token=YOUR_API_KEY" \
"https://api.perilpulse.com/v1/risks?address=123+Main+St&city=Austin&state=TX&zip=78701"
Get instant results
Receive comprehensive risk data in under 100ms.
Base URL
All API requests should be made to:
https://api.perilpulse.com/v1
Available Formats
- • JSON (default)
- • YAML (coming soon) - add
?format=yaml
Protocol
- • HTTPS only
- • TLS 1.2+ required
Risk Assessment
/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
GET /v1/risks?address=123+Main+St&city=Austin&state=TX&zip=78701
Authorization: Token token=YOUR_API_KEY
Example 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
}
Coming Soon
Enhanced Property Data/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
{
"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
}
}
Coming Soon
Replacement Cost Data🚧 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.
/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
{
"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"
}
}
Coming Soon
Combined Data Endpoints🚧 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:
/risks_and_enhanced_property
Coming Soon
Will return both risk assessment and enhanced property data in one call.
{
"risks": { /* risk data */ },
"enhanced_property": { /* property data */ }
}
/risks_and_enhanced_property_and_replacement_cost_data
Coming Soon
Will return risks, property data, and replacement cost in one comprehensive response.
{
"risks": { /* risk data */ },
"enhanced_property": { /* property data */ },
"replacement_cost_data": { /* replacement cost */ }
}
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
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 Handling
Error Response Format
{
"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"}
HTTP Status Codes
200
400
401
403
404
429
Code Examples
cURL
# 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
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
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
$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
// 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.
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 limitX-RateLimit-Remaining
- Remaining requestsX-RateLimit-Reset
- Reset timestamp
Need higher limits? Contact us for enterprise rate limits tailored to your needs.
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
Migration from HazardHub
Switching from HazardHub? It's easier than you think:
Update Base URL
Change from api.hazardhub.com
to api.perilpulse.com
Update API Key
Replace your HazardHub API key with your new PerilPulse key
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.