API Reference

Base URL: https://riskbeforebuy.smarttechinvest.com

Authentication

Pass your API key via the X-API-Key header on every request (except /v1/signup and /v1/login).

GET/v1/risk/:zip

Get risk scores for a U.S. ZIP code.

Parameters

Name	Type	Required	Description
zip	path	required	5-digit U.S. ZIP code
detail	query	optional	"county" (default) or "tract" (paid plans)

Response

{
  "success": true,
  "data": {
    "composite": 62,
    "flood": 28,
    "earthquake": 78,
    "wildfire": 42,
    "crime": 55,
    "county": "Los Angeles",
    "state": "CA",
    "fips": "06037"
  }
}

Error Codes

400 Invalid ZIP code
404 ZIP not found
429 Rate limit exceeded

GET/v1/risk/:zip/report

Get full risk report with NPV calculations.

Parameters

Name	Type	Required	Description
zip	path	required	5-digit U.S. ZIP code
format	query	optional	"json" (default) or "pdf"
years	query	optional	NPV projection years (default: 30)

Response

{
  "success": true,
  "data": {
    "scores": { "composite": 62, "flood": 28, ... },
    "npv30Year": 127000,
    "insuranceCosts": {
      "flood": 1200,
      "earthquake": 800,
      "fire": 450,
      "homeowners": 1800
    },
    "recommendation": "Moderate overall risk...",
    "dataUpdated": "2026-02-28"
  }
}

Error Codes

401 API key required
403 Plan upgrade required
429 Rate limit exceeded

GET/v1/risk/compare

Compare risk and costs for multiple locations.

Parameters

Name	Type	Required	Description
fips	query	required	FIPS county codes (repeat for multiple, e.g. ?fips=06037&fips=48201)
years	query	optional	NPV projection years (default: 30)

Response

{
  "success": true,
  "data": {
    "locations": [
      { "zip": "90210", "composite": 62, ... },
      { "zip": "94102", "composite": 71, ... }
    ],
    "npvDifference": 43000,
    "recommendation": "90210 has lower 30-year risk cost..."
  }
}

Error Codes

400 Invalid request body
401 API key required
429 Rate limit exceeded

GET/v1/hazards

List all available hazard types and their data sources.

Response

{
  "success": true,
  "data": [
    { "id": "flood", "name": "Flood Risk", "source": "FEMA NRI" },
    { "id": "earthquake", "name": "Earthquake Risk", "source": "USGS" },
    { "id": "wildfire", "name": "Wildfire Risk", "source": "USFS" },
    { "id": "crime", "name": "Crime Risk", "source": "FBI UCR" }
  ]
}

POST/v1/signup

Create an account and receive an API key.

Parameters

Name	Type	Required	Description
name	body	required	User display name
email	body	required	Email address
password	body	required	Password (min 8 characters)

Response

{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "free",
    "apiKey": "rbb_abc123..."
  }
}

Error Codes

400 Invalid input
409 Email already registered

POST/v1/login

Authenticate with email and password.

Parameters

Name	Type	Required	Description
email	body	required	Email address
password	body	required	Password

Response

{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "free",
    "apiKey": "rbb_abc123..."
  }
}

Error Codes

401 Invalid credentials

GET/v1/account

Get current account details.

Response

{
  "success": true,
  "data": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "tier": "free",
    "usage": { "today": 5, "limit": 100 }
  }
}

Error Codes

401 API key required

Rate Limiting

Requests that exceed your plan limit return 429 Too Many Requests with a Retry-After header indicating seconds until the limit resets.

Plan	Requests/Day	Tract-Level
Developer (Free)	100	No
Starter ($17/mo)	1,000	Yes
Business ($49/mo)	10,000	Yes
Enterprise (Custom)	Unlimited	Yes