What This Endpoint Does

Analyses Location: Finds the nearest weather station to your specified coordinates
Calculates Risk: Uses historical weather data to assess rainfall probability
Generates Options: Returns 2 pricing tiers (typically 40% and 100% payout levels)
Provides Transparency: Shows weather station details, trigger values, and premium breakdown

When to Use This Endpoint

Call this endpoint when:

A customer is browsing your offerings and wants to see insurance pricing
You need to show insurance costs during the booking flow
A customer changes their dates/location and needs updated pricing
You want to pre-calculate insurance options for your inventory

Request Parameters Explained

experienceDetails.type: The category of activity being insured

camping: Outdoor camping and caravan parks
hiking: Hiking trails and outdoor adventures
event: Outdoor events, festivals, concerts
sports: Sporting events and activities
experience: Tours, experiences, and activities
accommodation: Hotels, resorts, glamping

experienceDetails.location.coordinates: The exact location being insured

We'll find the nearest official weather station (typically within 50km)
The weather station distance affects pricing - closer stations may have better rates
Coordinates should be accurate to ensure proper coverage

coverage.startDate & endDate: When the insurance is active

Must be in YYYY-MM-DD format (e.g., "2025-03-15")
Start date cannot be in the past
Both dates must be within 12 months from today
End date must be after start date
Coverage includes both start and end dates (inclusive)

coverage.exposureAmount: The total booking/revenue value to protect

This is the maximum potential payout across all covered days
Should represent the actual financial risk (booking value, lost revenue, etc.)
Subject to minimum and maximum limits (contact support for current limits)
Currency is automatically determined by the location country

options.partnerQuoteId (optional): Your internal tracking reference

Use this to link the quote to your booking system
Helps with reconciliation and reporting
Will be included in policy responses for easy matching
Maximum 100 characters

Understanding the Response

The response includes:

quotes_generated: Number of pricing options (usually 2)

expires_at: When this quote expires (typically 3 hours from creation)

After expiration, you'll need to create a new quote
Ensures pricing reflects current weather conditions and risk

pricing_options[]: Array of coverage tiers

Each option has a unique quote_id - use this to purchase
payout_percentage: How much of the coverage amount is paid (50%, 75%, or 100%)
total_coverage: Maximum payout for the entire period
daily_coverage: Maximum payout per day
premium: What the customer pays for this option
is_voucher_option: Whether this option uses voucher payout (discount available)
voucher_discount_amount: Premium discount when selecting voucher payout
voucher_display_name: Display name for the voucher option

weather_protection: Details about the trigger mechanism

trigger_value: Rainfall amount in millimeters that activates payout
duration_hours: Time window for measuring rainfall (usually 24 hours)
weather_station: The official station monitoring rainfall for this policy

Date Restrictions (Important!)

12-Month Policy Creation Window

All coverage dates must fall within 12 months from today
This ensures we have reliable weather data for accurate pricing
If you need coverage beyond 12 months, create a new quote closer to the date

Why this restriction exists:

Weather patterns change over time
Seasonal data becomes more accurate closer to the coverage period
Prevents stale pricing that doesn't reflect current conditions

Example scenarios:

Today is January 15, 2025
Valid: Coverage from June 1-5, 2025 (5 months away)
Valid: Coverage from January 10-14, 2026 (12 months away)
Invalid: Coverage from February 1-5, 2026 (12.5 months away)

Pricing and Premium Breakdown

Each pricing option includes a detailed premium breakdown:

total_premium: The amount the customer pays (includes all taxes)
base_premium: The insurance cost before taxes
total_tax: Sum of all applicable taxes
tax_breakdown: Individual tax components (e.g., GST, stamp duty)
daily_rate: Cost per day of coverage

Taxes are automatically calculated based on the location's jurisdiction.

Common Use Cases

Scenario: Camping Booking Flow

1. Customer selects dates: March 15-18, 2025
2. Location: Sydney Tourist Park (-33.8727, 151.2057)
3. Booking value: $500
4. You call this endpoint to get quote options
5. Display the 3 pricing tiers to customer
6. Customer selects preferred option (e.g., 100% coverage for $67.50)

Error Handling

The endpoint validates all inputs before generating quotes. Common errors:

Validation Errors (400)

Invalid date format (must be YYYY-MM-DD)
Missing required fields
Invalid coordinates (outside valid ranges)
Invalid event type

Business Logic Errors (422)

Dates exceed 12-month limit
Start date in the past
End date before start date
Exposure amount outside limits
No weather stations found near location
Location not supported for coverage
Risk too high for coverage

Performance and Limits

Response Time: Typically 800ms
Rate Limiting: Contact support for current limits
Concurrent Requests: Supported, each request is independent
Quote Storage: Quotes are stored and retrievable via GET /quotes/{quote_id}

Best Practices

Show All Options: Present all pricing tiers to customers for transparency
Explain Payout Levels: Help customers understand 40% vs 100% coverage
Display Weather Station: Show the weather station name and distance to build trust
Handle Errors Gracefully: Provide clear feedback if coverage isn't available
Use Partner Quote ID: Always include your booking reference for tracking
Cache Wisely: Quotes are valid for 3 hours - don't create duplicates unnecessarily
Test in Sandbox: Always test with different locations and dates before production

Next Steps

After creating a quote:

Display the pricing options to your customer
When customer selects an option, use POST /quotes/{quote_id}/purchase to create the policy
Store the quote_id for the selected option
Complete payment processing in your system
Call the purchase endpoint with customer details and payment confirmation

Idempotency

This endpoint supports idempotency to prevent duplicate quotes:

Include an X-Request-Id header with a unique identifier
If the same request-id is sent again within 24 hours, the original quote is returned
This protects against accidental duplicate submissions
Recommended format: req-{timestamp}-{random} or use a UUID

Example with idempotency:

curl -X POST https://api.sandbox.weatherit.ai/v1/quotes \
  -H 'Authorization: Bearer sk_test_...' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: req-1705287000-abc123' \
  -d '{...}'