{ "openapi": "3.1.0", "info": { "title": "AtlasAdapt API", "version": "1.0.0", "summary": "Climate-resilience incentives, hardening costs and risk data for buildings.", "description": "AtlasAdapt models what it costs to harden a building against climate risk, what public money is\navailable to pay for it, and what the risk is worth avoiding. This API exposes that model.\n\n**Base URL.** `https://api.atlasadapt.com`. While that hostname is being set up, the identical\ngateway is also reachable at `https://atlasadapt.com/apigw` — same code, same data, same keys —\nso you can build against it today and change one constant later.\n\n**Authentication.** Every request carries a key issued by AtlasAdapt:\n\n```\ncurl -H \"Authorization: Bearer aa_live_...\" https://api.atlasadapt.com/v1/ping\n```\n\n`X-API-Key: aa_live_...` is accepted as an alternative. A key sent in the **query string is\nrefused** with HTTP 400 — query strings are recorded in access logs, browser history and Referer\nheaders, and none of those are revocable by us.\n\n**Start with `GET /v1/ping`.** It needs no grant and tells you what your key opens, when it\nexpires, and what you have spent this month — in your own timezone.\n\n**Grants.** Keys are scoped in two ways. *Route scopes* decide which endpoints you may call.\n*Field scopes* decide how much detail comes back from the endpoints you may call. Nothing is\nimplied: holding one grant never confers another, and every field scope is absent unless it was\ngranted explicitly.\n\n| Field scope | Adds |\n| --- | --- |\n| `incentives.eligibility` | Eligibility conditions, calculation formulas and the input factors a full assessment would still need |\n| `incentives.sources` | Research citations, harvest timestamps and change detection |\n| `incentives.funding` | Budget status: remaining funds, cohort rules and scheduled phase-outs |\n| `costs.provenance` | How a price was derived, its index basis, its sources and our confidence in it |\n| `estimate.trace` | The step-by-step derivation behind an estimate *(with the estimator endpoints)* |\n\nIf a field you expected is missing from a response, the grant is missing — not the data. Call\n`GET /v1/ping` to see exactly what your key holds.\n\n**Quota.** Requests are metered per calendar month **in your timezone**, so your month ends when\nyour month ends. `X-RateLimit-Remaining` is on every successful response. Refusals — bad\ncredentials, missing grants, our own outages — never count against you.\n\n### The funding contract\n\nRead this before you display or add up any incentive amount.\n\n| `availability.state` | Returned? | `counts_toward_roi` | What to do |\n| --- | --- | --- | --- |\n| *(expired)* | **Never** | — | Ended programmes are not in the API at all. |\n| `open` | Yes | `true` | Normal. Count it. |\n| `hiatus` | Yes | `false` | The budget is spent. Show it with the guidance; these are typically refunded annually. **Do not count it.** |\n| `waitlist` | Yes | `false` | Paused, but the grantor is still taking names. Tell your user to apply now. **Do not count it.** |\n\nTwo mistakes this prevents, and they fail in opposite directions. **Hiding** a paused programme\nloses your user a real award they may well receive next quarter. **Counting** one lets their\npayback figure assume money the grantor has said is not available.\n\nSeparately, `claimable_by_owner: false` marks a programme that is real money but **not the\nbuilding owner's to apply for** — a community or pass-through scheme. `applicant` names who can.\nNever add these to an owner's available funding.", "contact": { "name": "AtlasAdapt", "url": "https://atlasadapt.com", "email": "api@atlasadapt.com" } }, "servers": [ { "url": "https://api.atlasadapt.com", "description": "Production" }, { "url": "https://atlasadapt.com/apigw", "description": "Interim — while api.atlasadapt.com DNS is being set up" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your AtlasAdapt API key." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } }, "tags": [ { "name": "Key", "description": "Verifying a credential and reading its grants." }, { "name": "Incentives", "description": "Public funding: what exists, who awards it, what it is worth." }, { "name": "Reference", "description": "Costs, climate parameters and the vocabularies behind them." }, { "name": "Risk", "description": "Per-address and regional hazard data." }, { "name": "Estimators", "description": "Running the model: applicable incentives, payback and ROI." } ], "paths": { "/v1/ping": { "get": { "tags": [ "Key" ], "summary": "Verify a key and read its grants", "x-aa-route": "ping", "x-aa-scope": null, "description": "The only endpoint that needs no grant. Reports the key, its window, its grants and its usage — nothing about any other key, customer or data.", "responses": { "200": { "description": "The key, its grants and its usage this period.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/territories": { "get": { "tags": [ "Reference" ], "summary": "Countries this key may query", "x-aa-route": "territories.list", "x-aa-scope": "territories.list", "description": "Only the territories your key is licensed for. This list is the definitive answer to \"what can I ask about?\".", "responses": { "200": { "description": "Licensed territories with their currency and locale conventions.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/upgrades": { "get": { "tags": [ "Reference" ], "summary": "The hardening-measure vocabulary", "x-aa-route": "upgrades.catalogue", "x-aa-scope": "upgrades.catalogue", "description": "Every upgrade code, with the territories and modes in which it is actually priced. An upgrade absent for your territory is not modelled there.", "responses": { "200": { "description": "Upgrade codes with their territory and mode coverage.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/grantors": { "get": { "tags": [ "Incentives" ], "summary": "Bodies that award incentives", "x-aa-route": "grantors.list", "x-aa-scope": "grantors.list", "parameters": [ { "name": "territory", "in": "query", "required": false, "schema": { "type": "string", "example": "US" }, "description": "Optional. Omit for every territory your key is licensed for." } ], "responses": { "200": { "description": "Grantors and the areas they cover.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/incentives": { "get": { "tags": [ "Incentives" ], "summary": "List incentives", "x-aa-route": "incentives.list", "x-aa-scope": "incentives.list", "description": "Expired programmes are never returned. Read the funding contract above before summing any amount.\n\nGrant `incentives.eligibility` for conditions and formulas, `incentives.sources` for research citations, `incentives.funding` for budget status.", "parameters": [ { "name": "territory", "in": "query", "required": true, "schema": { "type": "string", "example": "US" }, "description": "ISO country code. Must be one your key is licensed for — see GET /v1/territories." }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "residential", "commercial" ] } }, { "name": "upgrade", "in": "query", "schema": { "type": "string", "example": "roof" }, "description": "Only incentives that apply to this upgrade code." }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Clamped to your key's ceiling. There is no \"all\"." } ], "responses": { "200": { "description": "A page of incentives, with the funding contract in `meta`.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/incentives/{id}": { "get": { "tags": [ "Incentives" ], "summary": "Read one incentive", "x-aa-route": "incentives.get", "x-aa-scope": "incentives.get", "description": "An expired programme returns 404 rather than a flagged record — so it cannot be cached and shown as live.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "sc:residential:sc_safe_home" } } ], "responses": { "200": { "description": "The incentive.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "404": { "description": "No such incentive, or the programme has ended.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/costs": { "get": { "tags": [ "Reference" ], "summary": "Hardening cost rules", "x-aa-route": "costs.list", "x-aa-scope": "costs.list", "description": "What a measure costs and what it saves. `formula` is the machine-readable rule. Grant `costs.provenance` to see how each price was derived and how confident we are in it.", "parameters": [ { "name": "territory", "in": "query", "required": true, "schema": { "type": "string", "example": "US" }, "description": "ISO country code. Must be one your key is licensed for — see GET /v1/territories." }, { "name": "building_type", "in": "query", "schema": { "type": "string", "example": "office" } }, { "name": "upgrade", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "residential", "commercial" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Clamped to your key's ceiling. There is no \"all\"." } ], "responses": { "200": { "description": "A page of cost rules.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/climate/params": { "get": { "tags": [ "Reference" ], "summary": "Climate risk parameters", "x-aa-route": "climate.params", "x-aa-scope": "climate.params", "description": "Business-interruption recovery curves and the escalators that age them forward.\n\n**The curve measures downtime, not damage.** Nodes are percentage of *normal operation* over time after an event. Reading `pct` as \"how much of the building was destroyed\" produces a plausible number about something else.\n\nOnly `fire`, `flood`, `heatwave` and `power_outage` vary by building type; `varies_by_building_type` marks which.", "parameters": [ { "name": "territory", "in": "query", "required": true, "schema": { "type": "string", "example": "US" }, "description": "ISO country code. Must be one your key is licensed for — see GET /v1/territories." }, { "name": "building_type", "in": "query", "schema": { "type": "string", "example": "office" } }, { "name": "risk", "in": "query", "schema": { "type": "string", "example": "flood" } } ], "responses": { "200": { "description": "Climate parameters for the territory.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/coverage/aggregate": { "get": { "tags": [ "Incentives" ], "summary": "Incentive counts by area", "x-aa-route": "coverage.aggregate", "x-aa-scope": "coverage.aggregate", "description": "Derived statistics only — counts and bands by area, never records or coordinates.", "parameters": [ { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "us", "eu" ], "default": "us" } }, { "name": "area", "in": "query", "schema": { "type": "string", "example": "US-FL" }, "description": "Country or region code, or CITY:Name." } ], "responses": { "200": { "description": "Counts and scale bands.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/usage": { "get": { "tags": [ "Key" ], "summary": "Your own usage and quota", "x-aa-route": "usage.self", "x-aa-scope": "usage.self", "description": "Your consumption over time, and where you stand against your monthly limit.\n\nReturns **your key only** — the filters are taken from the credential, not from the query string, so there is no parameter that could reach another customer's traffic.\n\nTwo clocks, deliberately separate: `quota.timezone` is your billing month; `history.timezone` is the clock the time series is bucketed in.", "parameters": [ { "name": "range", "in": "query", "schema": { "type": "string", "enum": [ "today", "3d", "1w", "2w", "1m", "3m", "6m", "1y", "all" ], "default": "1m" } } ], "responses": { "200": { "description": "Quota position and a bucketed time series.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/geo/resolve": { "get": { "tags": [ "Risk" ], "summary": "Resolve an address", "x-aa-route": "geo.resolve", "x-aa-scope": "geo.resolve", "description": "Address to coordinates, administrative area and flood zone. The cheap half of the risk surface — use this when you only need to know *where* a building is.\n\n**Three outcomes, deliberately distinct.** `200` resolved. `422` the address is not resolvable, so fix the input — retrying will not help. `503` our geocoder did not answer, and the address may be perfectly good; `Retry-After` says when to come back. Collapsing the last two would have you correcting addresses that were never wrong.\n\nCheck `granularity` before using the coordinates for anything boundary-sensitive: a postcode centroid and a rooftop match are both \"resolved\" and are not the same thing.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "2500 Edwards Dr, Fort Myers, FL" } }, { "name": "country", "in": "query", "schema": { "type": "string", "default": "us", "example": "us" } } ], "responses": { "200": { "description": "Location, administrative area and flood zone.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/risk/address": { "get": { "tags": [ "Risk" ], "summary": "Per-address hazard profile", "x-aa-route": "risk.address", "x-aa-scope": "risk.address", "description": "The hazards at one building, from the same lookup the AtlasAdapt product uses — so a figure you read here is the figure the product would show.\n\n**Coverage is not uniform, and the response says so.**\n\n| Country | Typical hazards returned |\n| --- | --- |\n| `us` | **15** — coldwave, earthquake, flood, hail, heat, hurricane, icestorm, landslide, outage, riverine, surge, tornado, wildfire, wind, winter |\n| `fr` | **8** — earthquake, flood, groundwater, heat, outage, subsidence, wildfire, wind |\n| `de` | **6** — earthquake, flood, hail, heat, outage, wind |\n| `ch` | **6** — flood, hail, heat, outage, wind, winter |\n| `uk` | **3** — flood.fluvial, flood.pluvial, subsidence |\n\nFrance varies by commune, so treat that row as typical rather than fixed. Do not hard-code any of\nthese lists: read the keys you are given.\n\nA hazard that is **absent** was never modelled for that country. A hazard marked `unavailable` **was** modelled and could not be answered this time. Those are different claims and a short list is not a finding of low risk — `meta.coverage` states both counts.\n\nIndividual hazards also carry their own honesty: German `wind` is derived from a mean-wind grid rather than extreme-wind return periods, and says so in its `confidence` and `caveat`. Read those before treating any single figure as authoritative.\n\nAnswers are cached 30 days, so repeated calls for one address are cheap and stable.", "parameters": [ { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "example": "2500 Edwards Dr, Fort Myers, FL" } }, { "name": "country", "in": "query", "schema": { "type": "string", "enum": [ "us", "de", "ch", "fr", "uk" ], "default": "us" } }, { "name": "utility", "in": "query", "schema": { "type": "string" }, "description": "US only. Names the electricity utility for outage statistics." } ], "responses": { "200": { "description": "Hazard levels with sources, confidence and attribution.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "422": { "description": "The address could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "503": { "description": "An upstream hazard source did not answer. Retry-After says when.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/risk/surface": { "get": { "tags": [ "Risk" ], "summary": "Regional hazard surface", "x-aa-route": "risk.surface", "x-aa-scope": "risk.surface", "description": "One value per region, for shading a map. Region codes, names and numbers only — never coordinates or sample points.\n\nEvery region carries both `mean` (the average across its sample points) and `max` (the worst single one). A map shading *\"could it happen here\"* wants `max`; one shading *\"what is it like here\"* wants `mean`.\n\nThis is **not** a substitute for `/v1/risk/address` — a region value cannot tell you about a building.", "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "us", "de", "ch", "fr", "uk" ], "example": "de" } }, { "name": "hazard", "in": "query", "schema": { "type": "string", "example": "flood" }, "description": "Omit for every hazard in one payload." }, { "name": "metric", "in": "query", "schema": { "type": "string" }, "description": "US only — selects among the FEMA NRI measures. Ignored elsewhere." } ], "responses": { "200": { "description": "Per-region hazard values with units and method.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/estimate/incentives": { "post": { "tags": [ "Estimators" ], "summary": "Which incentives apply, and for how much", "x-aa-status": "planned", "x-aa-route": "estimate.incentives", "x-aa-scope": "estimate.incentives", "responses": { "200": { "description": "Applicable incentives with computed amounts.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/estimate/roi": { "post": { "tags": [ "Estimators" ], "summary": "Payback, net cost and ROI", "x-aa-status": "planned", "x-aa-route": "estimate.roi", "x-aa-scope": "estimate.roi", "responses": { "200": { "description": "The priced plan.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } }, "/v1/estimate/portfolio": { "post": { "tags": [ "Estimators" ], "summary": "ROI across many sites", "x-aa-status": "planned", "x-aa-route": "estimate.portfolio", "x-aa-scope": "estimate.portfolio", "responses": { "200": { "description": "Per-site and aggregate results.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Malformed request, or the key was sent in the URL.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "401": { "description": "The key is missing, malformed, unknown or revoked. These are deliberately indistinguishable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "403": { "description": "The key is valid but not yet active, expired, suspended, or does not grant this.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "429": { "description": "Burst limit or monthly quota reached. See Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } }, "500": { "description": "Something went wrong at our end.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable identifier. Branch on this, never on the message." }, "message": { "type": "string", "description": "Human-readable explanation. Wording may change; the code will not." }, "scope": { "type": "string", "description": "On scope_denied and quota_exceeded, the grant or cap involved." }, "docs_url": { "type": "string" }, "request_id": { "type": "string", "description": "Quote this when asking us about a call." } } } } } } } } } } } }, "x-aa-errors": [ [ "invalid_request", 400, "A parameter is missing or malformed." ], [ "key_in_query_string", 400, "The key was sent in the URL. Use the Authorization header — query strings are logged, cached and forwarded in Referer headers, and we cannot un-leak them." ], [ "invalid_key", 401, "Missing, malformed, unknown or revoked. These four are deliberately indistinguishable: telling them apart would let anyone confirm whether a key they found is genuine." ], [ "key_not_yet_active", 403, "The key is valid but its start date has not arrived. The response tells you when, in your timezone." ], [ "key_expired", 403, "The key is valid but past its end date. Ask us to extend it — your credential does not change." ], [ "key_suspended", 403, "The key has been suspended. Contact us." ], [ "scope_denied", 403, "Your key does not grant this endpoint or territory. The response names the missing grant." ], [ "origin_denied", 403, "Browser request from an origin this key does not permit." ], [ "ip_denied", 403, "Request from an address outside this key's allowlist." ], [ "not_found", 404, "No such resource — or, for an incentive, a programme that has ended." ], [ "method_not_allowed", 405, "That path exists under a different method." ], [ "unprocessable", 422, "Understood but unfulfillable — for example an address we cannot locate. This one does count against your quota, because the upstream lookup was still made." ], [ "rate_limited", 429, "Too many requests in one minute. Retry-After tells you how long to wait." ], [ "quota_exceeded", 429, "The monthly allowance for this key, or for this endpoint, is spent. The response names which, and when it resets in your timezone." ], [ "server_error", 500, "Our fault. Not counted against your quota. Quote the request_id." ], [ "upstream_unavailable", 503, "A third-party data source is down. Not counted against your quota." ] ] }