Getting Started

The ClimateNest Enterprise API provides programmatic access to AI-powered climate risk assessments for any Australian residential address. Integrate climate intelligence directly into your property platforms, buyer portals, mortgage tools, and risk dashboards.

Base URL: https://climatenest.org/api/v1

All requests and responses use application/json. All monetary values are in AUD.

Authentication

Authenticate using your API key via the Authorization: Bearer header, X-API-Key header, or ?api_key= query parameter. Generate keys from Dashboard → Enterprise tab after purchasing an Enterprise pack.

POST /v1/risk-assessment HTTP/1.1
Host: climatenest.org
Content-Type: application/json
Authorization: Bearer cne_live_YOUR_API_KEY

Alternatively: X-API-Key: cne_live_YOUR_API_KEY

Keep your API key confidential. Do not expose it in client-side code or public repositories. Rotate compromised keys immediately from your dashboard.

Endpoints

{
  "success": true,
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2025-03-06T08:00:00Z",
  "address": "14 River Street, Lismore NSW 2480",
  "report_type": "full",
  "credits_used": 1,
  "credits_remaining": 24,
  "response_time_ms": 4521,
  "data": {
    "address": "14 River Street, Lismore NSW 2480",
    "climateNestIndex": {
      "overall": 84,
      "current": 84,
      "projection2030": 96,
      "projection2050": 100,
      "rating": "Severe"
    },
    "hazardScores": {
      "flood": { "score": 97, "acsRiskCategory": "Severe", "confidence": 90 },
      "bushfire": { "score": 12, "acsRiskCategory": "Low", "confidence": 85 },
      "heat": { "score": 61, "acsRiskCategory": "High", "confidence": 70 },
      "coastal": { "score": 5, "acsRiskCategory": "Low", "confidence": 95 },
      "wind": { "score": 45, "acsRiskCategory": "Moderate", "confidence": 65 },
      "storm": { "score": 72, "acsRiskCategory": "High", "confidence": 60 }
    },
    "financialAnalysis": {
      "insuranceTrajectory": {
        "currentPremium": 2800,
        "projected2030": 3500,
        "projected2050": 5200
      }
    },
    "recommendedActions": [
      "Consider flood insurance as a priority.",
      "Review flood mitigation works on the property.",
      "Check council flood overlays before purchasing."
    ]
  },
  "branding": {
    "logo_url": "https://...",
    "primary_color": "#1a7a5a",
    "business_name": "My Agency"
  }
}

Batch

The POST /v1/risk-assessment/batch endpoint processes up to 25 addresses in a single request. Each address is processed sequentially and consumes 1 credit. When an individual address fails, its credit is automatically restored and processing continues with the next address.

{
  "success": true,
  "request_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
  "timestamp": "2026-06-19T12:00:00Z",
  "batch_size": 3,
  "processed": 2,
  "failed": 1,
  "credits_used": 2,
  "credits_rolled_back": 1,
  "credits_remaining": 22,
  "results": [
    {
      "address": "14 River Street Lismore NSW 2480",
      "report_type": "full",
      "data": {}
    }
  ],
  "errors": [
    { "address": "Bad Address", "error": "Address must be at least 5 characters." }
  ]
}

Rate Limits

Each API key has a configurable rate limit (default 10 requests per minute). You can adjust this per key from your Enterprise dashboard (up to 100 req/min). Requests exceeding the limit receive a 429 response with a Retry-After header.

To increase throughput, generate multiple API keys from your Enterprise dashboard. Each key has its own independent rate limit bucket. Contact [email protected] for custom rate limit arrangements.

Pricing & Credits

How credits work

Each API request consumes 1 credit per address. A single-address call to /v1/risk-assessment uses 1 credit. A batch call with 10 addresses uses 10 credits.

• Successful requests — credit deducted after report generation. You only pay for completed reports.
• Failed requests — credit is automatically restored. If generation fails for any reason, your credit is refunded to your balance.
• Batch partial failures — only successful addresses are charged. Failed ones have their credits rolled back.
• Credit expiry — credits expire 12 months from purchase. Unused credits do not roll over beyond expiry.

You can check your balance any time in the Enterprise dashboard or inspect the credits_remaining field in every API response. When your balance reaches zero, the API returns a 402 response.

Enterprise packs

Purchase a pack from the Pricing page. All prices are in AUD, exclusive of GST.

White-Label

Enterprise customers can apply custom branding to API responses and PDF reports. Configure your logo, brand colours, company name, and footer text from Dashboard → Enterprise → White-Label Settings. Once active, all API responses from your key will automatically include your white-label branding in the branding field and any generated PDFs will use your custom logo, colours, and company name.

{
  "branding": {
    "logo_url": "https://climatenest.org/storage/v1/object/public/logos/user_abc/logo.png",
    "primary_color": "#1a7a5a",
    "business_name": "Acme Realty"
  }
}

White-label branding is resolved automatically from the API key owner's settings. No extra parameter is required — just configure your white-label settings once in the dashboard.

Code Examples

cURL

curl -X POST https://climatenest.org/api/v1/risk-assessment -H "Content-Type: application/json" -H "Authorization: Bearer cne_live_YOUR_KEY" -d '{"address": "14 River Street Lismore NSW 2480"}'

Python

import requests

response = requests.post(
    "https://climatenest.org/api/v1/risk-assessment",
    headers={
        "Authorization": "Bearer cne_live_YOUR_KEY",
        "Content-Type": "application/json",
    },
    json={"address": "14 River Street Lismore NSW 2480"},
)

data = response.json()
print(data["success"])          # true
print(data["credits_remaining"]) # e.g. 24
# Full report is in data["data"]

JavaScript / TypeScript

const response = await fetch(
  "https://climatenest.org/api/v1/risk-assessment",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer cne_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      address: "14 River Street Lismore NSW 2480",
    }),
  }
);

const data = await response.json();
console.log(data.success);           // true
console.log(data.credits_remaining); // e.g. 24
// Full report is in data.data

Batch (JavaScript)

const response = await fetch(
  "https://climatenest.org/api/v1/risk-assessment/batch",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer cne_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      addresses: [
        "14 River Street Lismore NSW 2480",
        "1 Smith Street Parramatta NSW 2150",
      ],
      report_type: "summary",
    }),
  }
);

const data = await response.json();
console.log(data.processed);  // 2
console.log(data.failed);     // 0
data.results.forEach(r => {
  console.log(r.address, r.data.climate_nest_index.rating);
});

Error Reference

All errors return a JSON body with error and message fields.

{
  "error": "insufficient_credits",
  "message": "No credits available. Purchase additional credits at https://climatenest.org/pricing",
  "credits_remaining": 0
}