AtlasAdapt API

Climate-resilience incentives, hardening costs and risk data for buildings.

AtlasAdapt models what it costs to harden a building against climate risk, what public money is available to pay for it, and what the risk is worth avoiding. This API exposes that model.

Base URL. https://api.atlasadapt.com. While that hostname is being set up, the identical gateway is also reachable at https://atlasadapt.com/apigw — same code, same data, same keys — so you can build against it today and change one constant later.

Authentication. Every request carries a key issued by AtlasAdapt:

curl -H "Authorization: Bearer aa_live_..." https://api.atlasadapt.com/v1/ping

X-API-Key: aa_live_... is accepted as an alternative. A key sent in the query string is refused with HTTP 400 — query strings are recorded in access logs, browser history and Referer headers, and none of those are revocable by us.

Start with GET /v1/ping. It needs no grant and tells you what your key opens, when it expires, and what you have spent this month — in your own timezone.

Grants. Keys are scoped in two ways. Route scopes decide which endpoints you may call. Field scopes decide how much detail comes back from the endpoints you may call. Nothing is implied: holding one grant never confers another, and every field scope is absent unless it was granted explicitly.

Field scope	Adds
`incentives.eligibility`	Eligibility conditions, calculation formulas and the input factors a full assessment would still need
`incentives.sources`	Research citations, harvest timestamps and change detection
`incentives.funding`	Budget status: remaining funds, cohort rules and scheduled phase-outs
`costs.provenance`	How a price was derived, its index basis, its sources and our confidence in it
`estimate.trace`	The step-by-step derivation behind an estimate (with the estimator endpoints)

If a field you expected is missing from a response, the grant is missing — not the data. Call

GET /v1/ping to see exactly what your key holds.

Quota. Requests are metered per calendar month in your timezone, so your month ends when your month ends. X-RateLimit-Remaining is on every successful response. Refusals — bad credentials, missing grants, our own outages — never count against you.

The funding contract

Read this before you display or add up any incentive amount.

`availability.state`	Returned?	`counts_toward_roi`	What to do
(expired)	Never	—	Ended programmes are not in the API at all.
`open`	Yes	`true`	Normal. Count it.
`hiatus`	Yes	`false`	The budget is spent. Show it with the guidance; these are typically refunded annually. Do not count it.
`waitlist`	Yes	`false`	Paused, but the grantor is still taking names. Tell your user to apply now. Do not count it.

Two mistakes this prevents, and they fail in opposite directions. Hiding a paused programme loses your user a real award they may well receive next quarter. Counting one lets their payback figure assume money the grantor has said is not available.

Separately, claimable_by_owner: false marks a programme that is real money but not the building owner's to apply for — a community or pass-through scheme. applicant names who can. Never add these to an owner's available funding.

Key

Verifying a credential and reading its grants.

GET /v1/ping no grant required

Verify a key and read its grants

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.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/ping"

GET /v1/usage usage.self

Your own usage and quota

Your consumption over time, and where you stand against your monthly limit.

Returns 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.

Two clocks, deliberately separate: quota.timezone is your billing month; history.timezone is the clock the time series is bucketed in.

Parameters

Name	In	Type	Notes
`range`	query	`string` `today` `3d` `1w` `2w` `1m` `3m` `6m` `1y` `all`

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/usage"

Incentives

Public funding: what exists, who awards it, what it is worth.

GET /v1/grantors grantors.list

Bodies that award incentives

Parameters

Name	In	Type	Notes
`territory`	query	`string`	Optional. Omit for every territory your key is licensed for.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/grantors"

GET /v1/incentives incentives.list

List incentives

Expired programmes are never returned. Read the funding contract above before summing any amount.

Grant incentives.eligibility for conditions and formulas, incentives.sources for research citations, incentives.funding for budget status.

Parameters

Name	In	Type	Notes
`territory` *	query	`string`	ISO country code. Must be one your key is licensed for — see GET /v1/territories.
`mode`	query	`string` `residential` `commercial`
`upgrade`	query	`string`	Only incentives that apply to this upgrade code.
`page`	query	`integer`
`page_size`	query	`integer`	Clamped to your key's ceiling. There is no "all".

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/incentives?territory=US"

GET /v1/incentives/{id} incentives.get

Read one incentive

An expired programme returns 404 rather than a flagged record — so it cannot be cached and shown as live.

Parameters

Name	In	Type	Notes
`id` *	path	`string`

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/incentives/sc%3Aresidential%3Asc_safe_home"

GET /v1/coverage/aggregate coverage.aggregate

Incentive counts by area

Derived statistics only — counts and bands by area, never records or coordinates.

Parameters

Name	In	Type	Notes
`view`	query	`string` `us` `eu`
`area`	query	`string`	Country or region code, or CITY:Name.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/coverage/aggregate"

Reference

Costs, climate parameters and the vocabularies behind them.

GET /v1/territories territories.list

Countries this key may query

Only the territories your key is licensed for. This list is the definitive answer to "what can I ask about?".

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/territories"

GET /v1/upgrades upgrades.catalogue

The hardening-measure vocabulary

Every upgrade code, with the territories and modes in which it is actually priced. An upgrade absent for your territory is not modelled there.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/upgrades"

GET /v1/costs costs.list

Hardening cost rules

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	In	Type	Notes
`territory` *	query	`string`	ISO country code. Must be one your key is licensed for — see GET /v1/territories.
`building_type`	query	`string`
`upgrade`	query	`string`
`mode`	query	`string` `residential` `commercial`
`page`	query	`integer`
`page_size`	query	`integer`	Clamped to your key's ceiling. There is no "all".

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/costs?territory=US"

GET /v1/climate/params climate.params

Climate risk parameters

Business-interruption recovery curves and the escalators that age them forward.

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.

Only fire, flood, heatwave and power_outage vary by building type; varies_by_building_type marks which.

Parameters

Name	In	Type	Notes
`territory` *	query	`string`	ISO country code. Must be one your key is licensed for — see GET /v1/territories.
`building_type`	query	`string`
`risk`	query	`string`

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/climate/params?territory=US"

Risk

Per-address and regional hazard data.

GET /v1/geo/resolve geo.resolve

Resolve an address

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.

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.

Check 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	In	Type	Notes
`address` *	query	`string`
`country`	query	`string`

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/geo/resolve?address=2500%20Edwards%20Dr%2C%20Fort%20Myers%2C%20FL"

GET /v1/risk/address risk.address

Per-address hazard profile

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.

Coverage is not uniform, and the response says so.

Country	Typical hazards returned
`us`	15 — coldwave, earthquake, flood, hail, heat, hurricane, icestorm, landslide, outage, riverine, surge, tornado, wildfire, wind, winter
`fr`	8 — earthquake, flood, groundwater, heat, outage, subsidence, wildfire, wind
`de`	6 — earthquake, flood, hail, heat, outage, wind
`ch`	6 — flood, hail, heat, outage, wind, winter
`uk`	3 — flood.fluvial, flood.pluvial, subsidence

France varies by commune, so treat that row as typical rather than fixed. Do not hard-code any of these lists: read the keys you are given.

A 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.

Individual 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.

Answers are cached 30 days, so repeated calls for one address are cheap and stable.

Parameters

Name	In	Type	Notes
`address` *	query	`string`
`country`	query	`string` `us` `de` `ch` `fr` `uk`
`utility`	query	`string`	US only. Names the electricity utility for outage statistics.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/risk/address?address=2500%20Edwards%20Dr%2C%20Fort%20Myers%2C%20FL"

GET /v1/risk/surface risk.surface

Regional hazard surface

One value per region, for shading a map. Region codes, names and numbers only — never coordinates or sample points.

Every 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.

This is not a substitute for /v1/risk/address — a region value cannot tell you about a building.

Parameters

Name	In	Type	Notes
`country` *	query	`string` `us` `de` `ch` `fr` `uk`
`hazard`	query	`string`	Omit for every hazard in one payload.
`metric`	query	`string`	US only — selects among the FEMA NRI measures. Ignored elsewhere.

Example

curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
  "https://api.atlasadapt.com/v1/risk/surface?country=de"

Estimators

Running the model: applicable incentives, payback and ROI.

POST /v1/estimate/incentives estimate.incentives Coming soon

Which incentives apply, and for how much

POST /v1/estimate/roi estimate.roi Coming soon

Payback, net cost and ROI

POST /v1/estimate/portfolio estimate.portfolio Coming soon

ROI across many sites

Errors

Every error has the same shape. Branch on error.code, never on the message.

{
  "ok": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly request limit reached for this key.",
    "scope": "account",
    "docs_url": "https://api.atlasadapt.com/docs#errors",
    "request_id": "req_84213"
  }
}

Refusals are free. 401, 403, 429 and every 5xx are never counted against your monthly allowance. You cannot lose a month you have paid for to a bad credential or to an outage of ours. 422 is the one exception, because the upstream lookup was still made.

Code	HTTP	Meaning
`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.