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.
Parameters. Country-scoped endpoints take country (US, DE, FR…). Four of them previously took territory; that spelling still works and answers with a deprecation note, but
territory is being reserved for groupings that span several countries.
Authentication. Every request carries a key issued by AtlasAdapt:
curl -H "Authorization: Bearer aa_live_..." https://api.atlasadapt.com/v1/pingX-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.
⚠️ One scope is not sold with the data: incentives.review. It returns our review state — when we last looked at a row and whether a person did — rather than anything about the programme. It is provided on request and requires a specific licence term, because it is a statement about how we work rather than about the funding, and because last_verified is written by automated passes as well as by people and is easily read as a guarantee it is not. Ask us for it; a metadata licence does not include it.
| Field scope | Adds |
|---|---|
incentives.eligibility | Eligibility conditions, calculation formulas, which part of the cost is eligible (calculation.eligible_expenses: equipment & materials, installation, or both; calculation.eligible_tax: 1 if the VAT / sales tax on them counts, 0 if not, null if not yet determined) and the input factors a full assessment would still need |
incentives.sources | A research block: the calculation source list as stored, when we harvested the rules, and when a source page was last seen to change. (Every cited URL is in source.urls for every key.) |
incentives.funding | Budget status: remaining funds, cohort rules and scheduled phase-outs |
incentives.review | On request, under an added licence term. Our own review state for a row: whether a person checked it (human_checked), when (checked_at), and the freshness stamp last_verified. ⚠️ Those are two different claims — last_verified is written by automated passes as well as people, so last_verified_is_automated tells you when no human signature stands behind it. Not included in a metadata licence by default. |
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. |
prioritised_other | Yes | false | The remaining money is reserved for other applicants. Show it; do not count it. |
closed | Yes | false | Not taking applications. Listed so the award is not lost if it reopens; do not count it. |
Every state but open carries amount_available: 0; open carries null, meaning "the stated amount". A status recorded by our automated checks is never stronger than waitlist: only a person marks a programme closed. A status past its review date reverts to open with lapsed: true — it was checked once and is now out of date.
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.
Stated conditions — show them wherever you show the incentive
Some criteria cannot be checked from data: "Standard or fossil-fuelled HVAC replacements are ineligible; qualifies only if specified as a high-efficiency or decarbonised unit." Every incentive carries conditions[], in the base payload with no grant needed. The amount assumes they are met, so display each condition beside the incentive, everywhere you display it — your user must never be able to say they were not told.
| Field | Meaning |
|---|---|
text | The condition, in ?lang= when translated |
lang | The language text is actually in (en when no translation exists yet) |
text_en | The original English |
upgrades | null = applies to every upgrade the incentive covers; otherwise show it only when one of these is part of what you display |
source | grantor — the programme's own requirement. atlasadapt — our note on what the figure takes for granted; show it as ours (the AtlasAdapt product prefixes it "We assumed:"), never as the grantor's words |
A programme whose conditions nobody can meet is not returned at all, like an expired one.
Disclaimer
Every response that carries incentive data has meta.contract.disclaimer:
> Unless otherwise stated in your contract the data here is © <current year> Atlas Adapt. All information is > provided as guidance and should be confirmed with the grantor of the incentive before applying.
That is /v1/incentives, /v1/incentives/{id}, /v1/grantors, /v1/coverage, /v1/estimate/incentives,
/v1/estimate/roi and a portfolio job's results.
Stacking — what may be claimed alongside what
stacking_rules is what a grantor says about combining its money with somebody else's. One rule can name several programmes, and several programmes can name one rule, so it is a list of objects rather than a field on each incentive.
Each entry has kind:
| kind | meaning |
|---|---|
stacks | may be claimed together, usually with conditions |
excludes | may not be claimed together |
capped | may be claimed together, but the total is limited |
⚠️ excludes and capped are stated, not yet enforced. The amounts in /v1/estimate/* do not currently apply them; treat them as information to show a reader, not as arithmetic we have done.
Each rule also carries id, summary (one sentence) and detail (the grantor's own terms, where we hold them).
On GET /v1/incentives each member of combines_with is the rule as stated:
{ type, role, incentive_id?, grantor_type?, label? } — type is incentive, grantor_type or
text, and role is subject (the programme the rule belongs to) or counterparty. A rule is listed on every incentive it names, subject or counterparty.
**On /v1/estimate/* the members are resolved for the building**, in three shapes, and the third matters:
- { incentive_id, name, role } — a programme in this response. - { grantor_type, incentive_ids } — a whole funding tier, e.g. every local-authority grant. On /v1/estimate/* the ids are resolved for that address; on /v1/incentives there is no address, so the rule is returned as stated and the ids are absent. An empty incentive_ids means we hold no such programme here — which is an answer, not a gap. - { label, modelled: false } — money the grantor points at that we do not model at all, such as pension-fund aid or a reduced VAT rate. It is named so a reader is not left concluding it does not exist; it is never in any total.
⚠️ Only members a person has confirmed are published. The admin also proposes members by reading the grantor's text; those are never returned here.
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.
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/ping"Response
The key, its grants and its usage this period.
Sample response to GET /v1/ping (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"key": {
"prefix": "aa_live_EXAMPLE1",
"label": "My integration",
"environment": "live",
"site": null,
"timezone": "Europe/London",
"starts_at": null,
"expires_at": null
},
"grants": {
"routes": [
"territories.list",
"upgrades.catalogue",
"grantors.list",
"incentives.list",
"incentives.get",
"costs.list",
"climate.params",
"coverage.aggregate",
"usage.self",
"geo.resolve",
"risk.address",
"risk.surface",
"estimate.roi",
"estimate.portfolio",
"estimate.incentives",
"estimate.supplychain"
],
"fields": [],
"territories": null
},
"site": null,
"usage": {
"period": "2026-09",
"timezone": "Europe/London",
"used": 0,
"limit": 100000,
"remaining": 100000,
"by_route": [],
"resets_at": "2026-10-01T00:00:00+01:00"
}
}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 | string9 values — what each means
|
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/usage"Response
Quota position and a bucketed time series.
Sample response to GET /v1/usage?range=today (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"quota": {
"period": "2026-09",
"timezone": "Europe/London",
"used": 9,
"limit": 100000,
"remaining": 99991,
"by_route": {
"climate.params": 1,
"costs.list": 1,
"coverage.aggregate": 1,
"grantors.list": 1,
"incentives.get": 1,
"incentives.list": 1,
"ping": 1,
"territories.list": 1,
"upgrades.catalogue": 1
},
"resets_at": "2026-10-01T00:00:00+01:00"
},
"history": {
"range": "today",
"granularity": "hour",
"timezone": "America/Denver",
"points": [
{
"t": "2026-09-26 00:00",
"label": "Sat 00:00",
"ok": 0,
"denied": 0,
"invalid": 0,
"upstream": 0,
"error": 0,
"total": 0
},
{
"t": "2026-09-26 01:00",
"label": "Sat 01:00",
"ok": 0,
"denied": 0,
"invalid": 0,
"upstream": 0,
"error": 0,
"total": 0
}
],
"points_sample_note": "sample shortened: 15 items in the real response, 2 shown",
"totals": {
"ok": 9,
"denied": 0,
"invalid": 0,
"upstream": 0,
"error": 0,
"total": 9
},
"by_endpoint": [
{
"key": "ping",
"label": "ping",
"n": 1
},
{
"key": "territories.list",
"label": "territories.list",
"n": 1
}
],
"by_endpoint_sample_note": "sample shortened: 9 items in the real response, 2 shown"
},
"meta": {
"timezones": "quota.timezone is YOUR billing month. history.timezone is the clock the time series is bucketed in. They are deliberately separate."
}
}Values in this response
| Field | Values | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
range | Usage range — what each means
|
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 | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country |
query | string12 values — what each means
|
Optional. Omit for every country your key is licensed for. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/grantors"Response
Grantors and the areas they cover.
Sample response to GET /v1/grantors?country=fr&page_size=2 (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"grantors": [
{
"id": "fr:ademe_agence_de_la_transition_ecologique",
"name": "ADEME (Agence de la transition écologique)",
"territory": "FR",
"type": "federal_national",
"coverage": {
"country": "FR"
}
},
{
"id": "fr:fr_anah",
"name": "Anah (Agence nationale de l'habitat)",
"territory": "FR",
"type": "federal_national",
"coverage": {
"country": "FR"
}
}
],
"grantors_sample_note": "sample shortened: 34 items in the real response, 2 shown",
"count": 34,
"meta": {
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
}
}
}Values in this response
| Field | Values | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | Grantor type — what each means
|
GET /v1/incentives incentives.list
List incentives
Expired programmes are never returned. Read the funding contract above before summing any amount.
total counts records; programmes counts programmes. Without mode, a programme held as a residential and a commercial record is two rows, so total ≥ programmes; with mode they are equal. Rows come in a fixed order (segment, position, id), so walking the pages returns each row exactly once.
A key tied to a site sees only the site's modes and upgrades, whether or not you send mode.
Each incentive carries applicant_types (who may apply — null means not yet recorded, never "everyone"), applicant_recorded, and building_types.
Grant incentives.eligibility for conditions and formulas, incentives.sources for research citations, incentives.funding for budget status.
Parameters
| Name | In | Type | Notes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country |
query | string12 values — what each means
|
Required, except with ref, which names its own country. ISO country code, case-insensitive. Must be one your key is licensed for — see GET /v1/countries. The United Kingdom is accepted as GB (ISO 3166-1) or UK. The former name "territory" still works but is deprecated. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mode |
query | string2 values — what each means
|
Omit for both. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrade |
query | string65 values — what each means
|
Only incentives that apply to this upgrade code. One upgrade code. Not every code is priced in every country — GET /v1/upgrades lists the ones your key can actually see. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ref |
query | string |
Narrow to one incentive by its short reference, such as FR18. Case-insensitive, and tolerant of the spacing and dashes people paste out of documents. country is not needed — ?ref=DE40 alone works, and the country is taken from the incentive itself. With no country, an unknown reference is a 404; with one, it returns an empty page (nothing by that reference in that country). A programme that serves homes AND businesses is two records, FR22r and FR22c; ?ref=FR22r narrows to one, and a bare ?ref=FR22 returns both (or the one your mode asks for). | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
org_type |
query | string9 values — what each means
|
Who is applying. state is the regional tier (US state, German Land, French région…); federal is national government. applicant_type is accepted as an alias.
Rows that have not been reviewed for who may apply are returned, not dropped and not assumed eligible: they carry | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_type |
query | string22 values — what each means
|
The building. One dimension, no subtypes: a town hall is office with org_type=local_government, a municipal depot is warehouse. The four home types select residential incentives; the rest commercial. The four site types (critical_infrastructure, infrastructure, natural_space, public_space) match only programmes that name them.
Two ids are British. The US spellings | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
measure_groups |
query | array |
The functional categories of measure the programme funds, derived from its upgrades. Use it to ask "what funding exists for this kind of work?" without knowing our upgrade codes.
One or several. Send a comma-separated list ( Codes. Our codes are lower snake_case (see Vocabularies › Measure group), in any case. A partner that has agreed its own group codes with us may send those instead, mixed freely with ours; responses always carry our codes. Programmes that fund only energy efficiency belong to no group and are never returned by this filter — a programme funding both energy and resilience keeps its resilience group and is. So this is also how to exclude energy-only schemes from a resilience recommendation. ⚠️ A valid group may return nothing. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
page |
query | integer |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
page_size |
query | integer |
Clamped to your key's ceiling. There is no "all". | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lang |
query | stringone of enfrdeitnlesdanbsv |
Language for conditions[].text. Falls back to English (and says so in conditions[].lang) where no translation exists yet. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/incentives"Response
A page of incentives, with the funding contract in meta. Each row carries both id (the stable slug you page and fetch by) and ref — a short quotable reference such as FR18, minted once per country and frozen, which is the same string our own reviewers use.
Reporting a problem? Quote the ref. It is the identifier our reviewers type into the admin console to open the exact programme, so a support message saying "FR18 pays the wrong amount" needs no further translation. id works too; ref is shorter and survives being read aloud.
Sample response to GET /v1/incentives?country=fr&org_type=local_government&building_type=school&page_size=2 (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"incentives": [
{
"id": "fr:commercial:ademe_heat_fund_renewable_heat_col",
"ref": "FR8",
"name": "ADEME Heat Fund — renewable heat/cold plant (surface geothermal, aerothermal, thalassothermal)",
"territory": "fr",
"mode": "commercial",
"grantor_id": "fr:ademe_agence_de_la_transition_ecologique",
"grantor_type": "federal_national",
"grantor_name": "ADEME (Agence de la transition écologique)",
"grantor_url": null,
"type": "subsidy",
"type_label": "Aide (subvention)",
"amount_label": "MWh EnR/an × 6 à 50 €/MWh selon la technologie × 20 ans, plafonné à 45 % des dépenses éligibles",
"amount_summary": null,
"is_cash": true,
"is_planning": false,
"is_annual": false,
"is_competitive": false,
"requires_ownership": true,
"claimable_by_owner": true,
"applicant": "owner",
"applicant_types": null,
"applicant_recorded": false,
"building_types": [
"restaurant",
"retail",
"office",
"warehouse",
"manufacturing",
"school",
"hospital",
"care_home",
"community_centre",
"sports_centre",
"emergency_services"
],
"upgrades": [
"heatpump",
"gshp"
],
"measure_groups": [],
"stacking": "stack",
"stacking_rule": "stackable_with_conditions",
"stacking_rules": [],
"stacking_notes": null,
"term_years": null,
"eligibility_summary": "In scope for a commercial/tertiary property owner (funds their own renewable heat plant). Distinct Fonds Chaleur strands exist for solaire thermique, biomasse, réseaux de chaleur.",
"source": {
"description": "ADEME — catalogue Agir 2026, chaleur/froid renouvelable",
"url": "https://agirpourlatransition.ademe.fr/entreprises/aides-financieres/catalogue/2026/installations-de-production-de-chaleur-et-de-froid-renouvelable-partir-de-geothermie-de-surface-daerothermie-ou-de-thalassothermie",
"urls": [
{
"url": "https://agirpourlatransition.ademe.fr/entreprises/aides-financieres/catalogue/2026/installations-de-production-de-chaleur-et-de-froid-renouvelable-partir-de-geothermie-de-surface-daerothermie-ou-de-thalassothermie",
"role": "programme",
"description": "ADEME — catalogue Agir 2026, chaleur/froid renouvelable",
"status": "unchecked"
},
{
"url": "https://www.sieml.fr/wp-content/uploads/2026/02/Conditions-deligibilite-financement-installation-geothermie-de-surface-et-aerothermie-2026.pdf",
"role": "calculation",
"description": null,
"status": "unchecked"
}
],
"urls_sample_note": "sample shortened: 3 items in the real response, 2 shown",
"confidence": "HIGH",
"is_estimate": true
},
"active_2026": "YES",
"availability": {
"state": "open",
"counts_toward_roi": true,
"amount_available": null,
"guidance": null,
"because": null,
"cohort_dependent": false
},
"conditions": []
},
{
"id": "fr:commercial:fprnm_barnier",
"ref": "FR12",
"name": "Fonds Barnier (FPRNM) — biens à usage professionnel (entreprises de moins de 20 salariés)",
"territory": "fr",
"mode": "commercial",
"grantor_id": "fr:fr_fprnm_ddtm",
"grantor_type": "federal_national",
"grantor_name": "État français — Fonds de Prévention des Risques Naturels Majeurs (FPRNM / Fonds Barnier)",
"grantor_url": "https://www.ecologie.gouv.fr/politiques-publiques/financement-prevention-risques-naturels-hydrauliques",
"type": "grant",
"type_label": "Grant",
"amount_label": "40% of eligible spend, capped at 10% of property market value. Business must have fewer than 20 employees.",
"amount_summary": "40% of eligible spend, for businesses with fewer than 20 employees. Eligible spend is itself capped at 10% of the property assessed value, so the grant cannot exceed 4% of that value. The rate was raised from 20% to 40% in May 2023.",
"is_cash": true,
"is_planning": false,
"is_annual": false,
"is_competitive": false,
"requires_ownership": false,
"claimable_by_owner": true,
"applicant": "owner",
"applicant_types": null,
"applicant_recorded": false,
"building_types": [
"restaurant",
"retail",
"office",
"warehouse",
"manufacturing",
"school",
"hospital",
"care_home",
"community_centre",
"sports_centre",
"emergency_services"
],
"upgrades": [
"flood",
"nonreturn_valve"
],
"measure_groups": [
"flood_exclusion",
"backflow_control"
],
"stacking": "stack",
"stacking_rule": null,
"stacking_rules": [],
"stacking_notes": null,
"term_years": null,
"eligibility_summary": "Business with under 20 employees; property in an approved PPRI/PPRL flood zone imposing measures, or in a PAPI commune; CatNat insurance required; vulnerability diagnosis required.",
"source": {
"description": "Arrete du 23/09/2021 (eligible works; item t gives professional goods the full residential list a-s, incl. (p) clapets anti-retour); Decret 2023-338 (40% rate); D. 561-12-7 (10%-of-value cap)",
"url": "https://www.georisques.gouv.fr/etre-accompagne/le-soutien-financier-du-fonds-barnier-0",
"urls": [
{
"url": "https://www.georisques.gouv.fr/etre-accompagne/le-soutien-financier-du-fonds-barnier-0",
"role": "programme",
"description": "Arrete du 23/09/2021 (eligible works; item t gives professional goods the full residential list a-s, incl. (p) clapets anti-retour); Decret 2023-338 (40% rate); D. 561-12-7 (10%-of-value cap)",
"status": "unchecked"
},
{
"url": "https://aida.ineris.fr/reglementation/arrete-230921-etablissant-liste-types-travaux-reduction-vulnerabilite-inondations",
"role": "calculation",
"description": null,
"status": "unchecked"
}
],
"urls_sample_note": "sample shortened: 5 items in the real response, 2 shown",
"confidence": "HIGH",
"is_estimate": false
},
"active_2026": "YES",
"availability": {
"state": "open",
"counts_toward_roi": true,
"amount_available": null,
"guidance": null,
"because": null,
"cohort_dependent": false
},
"conditions": []
}
],
"page": 1,
"page_size": 2,
"total": 7,
"total_pages": 4,
"meta": {
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
},
"applicant_unrecorded": 7,
"applicant_note": "Rows with applicant_recorded=false have not been reviewed for who may apply; they are returned, not assumed eligible."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
territory | Country — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mode | Incentive mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type | Incentive type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applicant | Applicant — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applicant_types[] | Organisation (applicant) type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_types[] | Building type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrades[] | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
active_2026 | Programme status — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
availability.state | Funding availability — what each means
|
Fields
| Field | Type | Meaning |
|---|---|---|
id | string | Stable slug; page and fetch by it. ⚠️ On 28 Sep 2026 each programme serving homes AND businesses became two records. The old id stayed with one of them (usually the residential one); the other got a new id. If your key cannot see the record an old id names, GET /v1/incentives/{id} returns its twin and names the id you asked for in meta.resolved_from, so you can store the new one. |
ref | string | Short quotable reference, e.g. FR18. Quote it in support messages. A programme that serves homes and businesses is two records whose refs end in r and c (FR22r, FR22c). |
twin_ref | string|null | For one half of a programme split by segment, the ref of the other half (FR22c on FR22r). Count the pair once when summing across segments. Null for a single-segment programme, and null when your key cannot be served the other half (it is disabled, ended, or outside your licence or site) — so a non-null value always fetches. |
twin_id | string|null | The id of the other half, under exactly the same rule as twin_ref: null unless your key can fetch it. |
name | string | The programme's name, as the grantor writes it. |
territory | string | Country code — see Vocabularies › Country. |
mode | string | residential or commercial. (both is being retired: each such programme becomes a residential and a commercial record sharing one reference number.) |
grantor_id | string | The awarding body, as a stable id. Never null. |
grantor_name | string | The awarding body's name, so a listing needs no second call to GET /v1/grantors. Never null. |
grantor_url | string|null | The awarding body's own site. Null where we hold no site for the grantor (a few local bodies); the programme's own page is always in source.url / source.urls. |
type | string | Incentive type — see Vocabularies › Incentive type. Never null. |
incentive_class | string | policy, financing, market or context — see Vocabularies › Incentive class. Never null. |
type_label | string | The programme's own word for what it is (Zuschuss, Subvención, Grant). Never null. |
amount_label | string|null | The amount in words, as the grantor states it. |
amount_summary | string|null | A shorter amount summary where one exists. |
is_cash | boolean | True when the reader receives money; false for loans, reliefs and discounts. |
is_annual | boolean | Paid every year rather than once. |
is_competitive | boolean | Awarded competitively — applying does not guarantee it. |
requires_ownership | boolean | Only the building's owner may apply. |
claimable_by_owner | boolean | False for community or pass-through programmes the owner cannot apply for. |
is_planning | boolean | True for a planning incentive: it pays for an energy audit, a renovation plan, design or project support, not for the upgrades themselves. Listed where the reader is eligible, always with amount 0, and never in any total. |
applicant | string | owner, or who applies instead where the owner cannot. |
applicant_types | string[]|null | Who may apply — see Vocabularies › Organisation type. null means not yet recorded, never "everyone". |
applicant_recorded | boolean | False when applicant_types is null. Show such a row as "check who may apply". |
building_types | string[] | The building types it serves — see Vocabularies › Building type. |
measure_groups | string[] | The functional categories of measure it funds, derived from upgrades — see Vocabularies › Measure group. Empty means the programme funds energy efficiency only, which is a classification, not a gap. |
upgrades | string[] | The upgrades it funds — see Vocabularies › Upgrade. |
stacking | string|null | Whether it combines with other programmes. |
stacking_rule | string|null | A one-word classification, e.g. always_stackable. It says nothing about WHICH programmes. |
stacking_rules | object[] | What the grantor says about combining this with other money, and who it names. See "Stacking" below. |
stacking_notes | string|null | The curator's note on combining it, where one is written. |
grantor_type | string | Never null. The funding tier: federal_national, state_province, city_county, utility, insurer, lender, nonprofit, other. |
term_years | integer|null | Duration, for loans and multi-year reliefs. |
eligibility_summary | string|null | Who and what qualifies, in brief. |
source | object | description (the grantor and page), url (the programme's own page), urls, confidence, is_estimate. ⚠️ Our own review state is NOT here — see the incentives.review scope. |
source.urls | object[] | Every page we cite for the programme, for every key. Each has url; role — programme (its own page), calculation (a page the amount is worked from), launch_date (where the application-window date comes from), commune_list (which communes qualify) or grantor (the awarding body's site); description (the page's own title as we last fetched it); and status — our link checker's last verdict: ok, broken, soft_404 (the page answers but says it is not found), non_specific (it resolves to a general page, not this programme), unverifiable (the site blocks automated checks) or unchecked. Cite a URL without a caveat only when status is ok. |
active_2026 | string|null | YES, CHECK, CONDITIONAL, LIKELY, N/A or null — see Vocabularies › Programme status. (NO is never returned: ended programmes are not in the API.) Whether money may be counted is availability.counts_toward_roi, not this field. |
availability | object | Funding status, on every incentive: state (see Vocabularies › Funding availability), counts_toward_roi, amount_available (0 for every state but open, whose null means "the stated amount"), guidance, because, cohort_dependent (some applicants face a different status; resolve it with the applicant's facts) and lapsed (the recorded status is past its review date, so open is not a fresh check). See the funding contract. |
conditions | object[] | Stated conditions to show wherever the incentive is shown; text in the requested lang. |
GET /v1/incentives/{id} incentives.get
Read one incentive
Accepts either form of identifier: the slug (fr:residential:cee) or the short reference (FR18). An expired programme returns 404 rather than a flagged record — so it cannot be cached and shown as live.
A reference quoted before a programme was split still works. A programme serving homes and businesses is two records, FR22r and FR22c. GET /v1/incentives/FR22r returns one. A bare GET /v1/incentives/FR22 returns the residential record in incentive (never null), a twins array naming both references, and both records in incentives — unless your key can see only one of them, in which case it is returned as a normal single record.
An id stored before 28 Sep 2026 still works. If it now names the half of a programme your key cannot see (a residential record, on a commercial-only key), the half you can see is returned, and meta.resolved_from names the id you sent — store incentive.id in its place.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id * |
path | string |
Either identifier. The slug — fr:residential:cee — or the short reference, FR18. The reference is what our own reviewers quote, so GET /v1/incentives/FR18 and a support message about FR18 name the same programme with no translation step. GET /v1/incentives?ref=FR18 does the same thing through the list endpoint if that suits your client better.
Slugs contain colons, never spaces. Send the slug as it is ( |
lang |
query | stringone of enfrdeitnlesdanbsv |
Language for conditions[].text. Falls back to English (and says so in conditions[].lang) where no translation exists yet. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/incentives/FR18"Response
The incentive. The same row shape as a list entry, plus whatever your grants allow — conditions and formula with incentives.eligibility, research with incentives.sources, funding with incentives.funding.
Sample response to GET /v1/incentives/FR18 (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"incentive": {
"id": "fr:residential:cee",
"ref": "FR18",
"name": "CEE Coup de pouce Chauffage (heat pump)",
"territory": "fr",
"mode": "residential",
"grantor_id": "fr:fr_edf",
"grantor_type": "federal_national",
"grantor_name": "EDF / Energy providers (CEE)",
"grantor_url": "https://www.economie.gouv.fr/particuliers/prime-energie-CEE",
"type": "grant",
"type_label": "Grant",
"amount_label": "€3,000-€5,000 by income band (kWhc × 5 calculation from Jan 2026)",
"amount_summary": null,
"is_cash": true,
"is_planning": false,
"is_annual": false,
"is_competitive": false,
"requires_ownership": false,
"claimable_by_owner": true,
"applicant": "owner",
"applicant_types": null,
"applicant_recorded": false,
"building_types": [
"single_family",
"townhouse",
"condo",
"multifamily"
],
"upgrades": [
"roofins",
"wallins",
"glazing",
"heatpump",
"valves"
],
"measure_groups": [],
"stacking": "stack",
"stacking_rule": "stackable_with_conditions",
"stacking_rules": [],
"stacking_notes": "Stackable with MaPrimeRénov'. Subject to total aid cap by income band. Cannot be combined with MaPrimeRénov' rénovation d'ampleur.",
"term_years": null,
"eligibility_summary": "Residential; replacing fossil fuel heating; any energy provider; income-tiered",
"source": {
"description": null,
"url": "https://www.ecologie.gouv.fr/politiques-publiques/coup-pouce-chauffage",
"urls": [
{
"url": "https://www.ecologie.gouv.fr/politiques-publiques/coup-pouce-chauffage",
"role": "programme",
"description": null,
"status": "unchecked"
},
{
"url": "https://www.ecologie.gouv.fr/sites/default/files/documents/BAR-TH-171%20vA78.4%20%C3%A0%20compter%20du%2001-01-2026_1.pdf",
"role": "calculation",
"description": null,
"status": "unchecked"
}
],
"urls_sample_note": "sample shortened: 4 items in the real response, 2 shown",
"confidence": "MEDIUM",
"is_estimate": true
},
"active_2026": "YES",
"availability": {
"state": "open",
"counts_toward_roi": true,
"amount_available": null,
"guidance": null,
"because": null,
"cohort_dependent": false
},
"conditions": []
},
"meta": {
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
}
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
territory | Country — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mode | Incentive mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type | Incentive type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applicant | Applicant — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applicant_types[] | Organisation (applicant) type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_types[] | Building type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrades[] | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
active_2026 | Programme status — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
availability.state | Funding availability — what each means
|
Fields
| Field | Type | Meaning |
|---|---|---|
id | string | Stable slug; page and fetch by it. ⚠️ On 28 Sep 2026 each programme serving homes AND businesses became two records. The old id stayed with one of them (usually the residential one); the other got a new id. If your key cannot see the record an old id names, GET /v1/incentives/{id} returns its twin and names the id you asked for in meta.resolved_from, so you can store the new one. |
ref | string | Short quotable reference, e.g. FR18. Quote it in support messages. A programme that serves homes and businesses is two records whose refs end in r and c (FR22r, FR22c). |
twin_ref | string|null | For one half of a programme split by segment, the ref of the other half (FR22c on FR22r). Count the pair once when summing across segments. Null for a single-segment programme, and null when your key cannot be served the other half (it is disabled, ended, or outside your licence or site) — so a non-null value always fetches. |
twin_id | string|null | The id of the other half, under exactly the same rule as twin_ref: null unless your key can fetch it. |
name | string | The programme's name, as the grantor writes it. |
territory | string | Country code — see Vocabularies › Country. |
mode | string | residential or commercial. (both is being retired: each such programme becomes a residential and a commercial record sharing one reference number.) |
grantor_id | string | The awarding body, as a stable id. Never null. |
grantor_name | string | The awarding body's name, so a listing needs no second call to GET /v1/grantors. Never null. |
grantor_url | string|null | The awarding body's own site. Null where we hold no site for the grantor (a few local bodies); the programme's own page is always in source.url / source.urls. |
type | string | Incentive type — see Vocabularies › Incentive type. Never null. |
incentive_class | string | policy, financing, market or context — see Vocabularies › Incentive class. Never null. |
type_label | string | The programme's own word for what it is (Zuschuss, Subvención, Grant). Never null. |
amount_label | string|null | The amount in words, as the grantor states it. |
amount_summary | string|null | A shorter amount summary where one exists. |
is_cash | boolean | True when the reader receives money; false for loans, reliefs and discounts. |
is_annual | boolean | Paid every year rather than once. |
is_competitive | boolean | Awarded competitively — applying does not guarantee it. |
requires_ownership | boolean | Only the building's owner may apply. |
claimable_by_owner | boolean | False for community or pass-through programmes the owner cannot apply for. |
is_planning | boolean | True for a planning incentive: it pays for an energy audit, a renovation plan, design or project support, not for the upgrades themselves. Listed where the reader is eligible, always with amount 0, and never in any total. |
applicant | string | owner, or who applies instead where the owner cannot. |
applicant_types | string[]|null | Who may apply — see Vocabularies › Organisation type. null means not yet recorded, never "everyone". |
applicant_recorded | boolean | False when applicant_types is null. Show such a row as "check who may apply". |
building_types | string[] | The building types it serves — see Vocabularies › Building type. |
measure_groups | string[] | The functional categories of measure it funds, derived from upgrades — see Vocabularies › Measure group. Empty means the programme funds energy efficiency only, which is a classification, not a gap. |
upgrades | string[] | The upgrades it funds — see Vocabularies › Upgrade. |
stacking | string|null | Whether it combines with other programmes. |
stacking_rule | string|null | A one-word classification, e.g. always_stackable. It says nothing about WHICH programmes. |
stacking_rules | object[] | What the grantor says about combining this with other money, and who it names. See "Stacking" below. |
stacking_notes | string|null | The curator's note on combining it, where one is written. |
grantor_type | string | Never null. The funding tier: federal_national, state_province, city_county, utility, insurer, lender, nonprofit, other. |
term_years | integer|null | Duration, for loans and multi-year reliefs. |
eligibility_summary | string|null | Who and what qualifies, in brief. |
source | object | description (the grantor and page), url (the programme's own page), urls, confidence, is_estimate. ⚠️ Our own review state is NOT here — see the incentives.review scope. |
source.urls | object[] | Every page we cite for the programme, for every key. Each has url; role — programme (its own page), calculation (a page the amount is worked from), launch_date (where the application-window date comes from), commune_list (which communes qualify) or grantor (the awarding body's site); description (the page's own title as we last fetched it); and status — our link checker's last verdict: ok, broken, soft_404 (the page answers but says it is not found), non_specific (it resolves to a general page, not this programme), unverifiable (the site blocks automated checks) or unchecked. Cite a URL without a caveat only when status is ok. |
active_2026 | string|null | YES, CHECK, CONDITIONAL, LIKELY, N/A or null — see Vocabularies › Programme status. (NO is never returned: ended programmes are not in the API.) Whether money may be counted is availability.counts_toward_roi, not this field. |
availability | object | Funding status, on every incentive: state (see Vocabularies › Funding availability), counts_toward_roi, amount_available (0 for every state but open, whose null means "the stated amount"), guidance, because, cohort_dependent (some applicants face a different status; resolve it with the applicant's facts) and lapsed (the recorded status is past its review date, so open is not a fresh check). See the funding contract. |
conditions | object[] | Stated conditions to show wherever the incentive is shown; text in the requested lang. |
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 | string2 values — what each means
|
|||||||
area |
query | string |
Country or region code, or CITY:Name. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/coverage/aggregate"Response
Counts and scale bands.
Sample response to GET /v1/coverage/aggregate?view=eu&area=FR (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"coverage": {
"ok": true,
"view": "eu",
"level": "country",
"country": null,
"filters_applied": {
"res_or_com": [],
"risks": [],
"upgrades": [],
"grantor_types": [],
"incentive_types": [],
"include_planning": true
},
"counting_rule": "distinct_incentive_id",
"scale": {
"mode": "auto",
"bands": [
{
"band": 0,
"slot": 0,
"min": 1,
"max": 10,
"count": 3,
"label": "1–10 programs"
},
{
"band": 1,
"slot": 1,
"min": 11,
"max": 20,
"count": 3,
"label": "11–20 programs"
}
],
"bands_sample_note": "sample shortened: 4 items in the real response, 2 shown"
},
"areas": [
{
"code": "AL",
"name": "Albania",
"total": 0,
"band": null,
"no_data": true
},
{
"code": "AT",
"name": "Austria",
"total": 16,
"band": 1,
"by_segment": {
"residential": 15,
"commercial": 3
},
"by_risk": {
"heatwave": 14,
"power_outage": 8,
"hail": 6,
"storm": 6,
"flood": 1
},
"by_grantor": {
"state_province": 10,
"federal_national": 3,
"lender": 1,
"other": 1,
"city_county": 1
},
"by_type": {
"grant": 13,
"subsidised_loan": 1,
"loan": 1,
"insurance_credit": 1
},
"conditional": 1
}
],
"areas_sample_note": "sample shortened: 40 items in the real response, 2 shown",
"totals": {
"areas_with_coverage": 11,
"areas_with_none": 29,
"distinct_incentives": 218
},
"as_of": "September 2026"
},
"meta": {
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
}
}
}Values in this response
| Field | Values | ||||||
|---|---|---|---|---|---|---|---|
view | Coverage view — what each means
|
Reference
Costs, climate parameters and the vocabularies behind them.
GET /v1/countries territories.list
Countries this key may query
Only the countries your key is licensed for. This list is the definitive answer to "what can I ask about?".
Also served at the former path /v1/territories, which still works but is deprecated. The scope is still named territories.list — renaming it would revoke the endpoint for every key that already holds it.
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/countries"Response
Licensed countries with their currency and locale conventions.
Sample response to GET /v1/countries (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"territories": [
{
"code": "AT",
"name": "Austria",
"currency": "EUR",
"locale": "de-AT",
"primary_language": "de",
"climate_region": "europe"
},
{
"code": "DK",
"name": "Denmark",
"currency": "DKK",
"locale": "da-DK",
"primary_language": "da",
"climate_region": "europe"
}
],
"territories_sample_note": "sample shortened: 12 items in the real response, 2 shown",
"count": 12
}GET /v1/upgrades upgrades.catalogue
The hardening-measure vocabulary
Every upgrade code, with the countries and modes in which it is actually priced. An upgrade absent for your country is not modelled there.
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/upgrades"Response
Upgrade codes with their country and mode coverage.
Sample response to GET /v1/upgrades (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"upgrades": [
{
"code": "aero",
"territories": [
"ES",
"IT"
],
"modes": [
"residential"
]
},
{
"code": "air",
"territories": [
"AT",
"CH",
"DE",
"DK",
"ES",
"FR",
"IT",
"NL",
"NO",
"SE",
"UK",
"US"
],
"modes": [
"commercial"
]
}
],
"upgrades_sample_note": "sample shortened: 57 items in the real response, 2 shown",
"count": 57,
"meta": {
"source": "Derived from priced cost rules. An upgrade is listed for a territory only where a cost rule prices it there."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
code | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
modes[] | Mode — what each means
|
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country * |
query | string12 values — what each means
|
ISO country code, case-insensitive. Must be one your key is licensed for — see GET /v1/countries. The United Kingdom is accepted as GB (ISO 3166-1) or UK. The former name "territory" still works but is deprecated. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_type |
query | string5 values — what each means
|
Omit for all. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrade |
query | string65 values — what each means
|
One upgrade code. Not every code is priced in every country — GET /v1/upgrades lists the ones your key can actually see. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mode |
query | string2 values — what each means
|
Omit for both. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
page |
query | integer |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
page_size |
query | integer |
Clamped to your key's ceiling. There is no "all". |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/costs?country=US"Response
A page of cost rules.
Sample response to GET /v1/costs?country=de&building_type=office&upgrade=heatpump&page_size=2 (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"costs": [
{
"id": "de:office:heatpump",
"territory": "de",
"mode": "commercial",
"upgrade": "heatpump",
"building_type": "office",
"formula": [
{
"fixed": "4300"
},
{
"perUnit": "34.72",
"of": "area"
}
],
"formula_sample_note": "sample shortened: 3 items in the real response, 2 shown",
"insurance_saving": 0,
"energy_saving": 5250,
"owner_only": false,
"vat_basis": "net",
"is_estimate": true
}
],
"page": 1,
"page_size": 2,
"total": 1,
"total_pages": 1,
"meta": {
"currency": "Costs are expressed in the territory currency (see /v1/territories).",
"estimates": "Rules with is_estimate = true are modelled, not sourced from a national price. Grant costs.provenance to see how each was derived."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
territory | Country — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mode | Mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrade | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_type | Cost building type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
vat_basis | VAT basis — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cost_basis | Cost basis — what each means
|
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 | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country * |
query | string12 values — what each means
|
ISO country code, case-insensitive. Must be one your key is licensed for — see GET /v1/countries. The United Kingdom is accepted as GB (ISO 3166-1) or UK. The former name "territory" still works but is deprecated. | ||||||||||||||||||||||||||
building_type |
query | string5 values — what each means
|
Omit for all. | ||||||||||||||||||||||||||
risk |
query | string11 values — what each means
|
Omit for all. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/climate/params?country=US"Response
Climate parameters for the country.
Sample response to GET /v1/climate/params?country=de&building_type=office&risk=flood (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"climate": [
{
"id": "de:office:flood",
"territory": "DE",
"building_type": "office",
"risk": "flood",
"archetype": "C",
"recovery_curve": {
"time_unit": "days",
"axis_max": 60,
"without": [
{
"id": "pre_event",
"label": "Before event",
"t": 0,
"pct": 100,
"dragX": false,
"dragY": false,
"locked": true
},
{
"id": "closure_floor",
"label": "Closure floor",
"t": 0,
"pct": 0,
"dragX": false,
"dragY": true
}
],
"without_sample_note": "sample shortened: 4 items in the real response, 2 shown",
"with": null
},
"frequency": 3,
"escalator_pct_per_year": null,
"escalator_source": {
"level": "region",
"key": "europe",
"value": 2
},
"base_year": 2026,
"is_estimate": true,
"source": {
"description": "JRC BN-FLEMOps (Steinhausen et al 2022); Munich Re NatCatSERVICE",
"url": "https://publications.jrc.ec.europa.eu/repository/handle/JRC124751",
"curve_description": "JRC BN-FLEMOps",
"curve_url": "https://publications.jrc.ec.europa.eu/repository/handle/JRC124751",
"confidence": "MEDIUM",
"last_verified": "2026-07-02"
},
"varies_by_building_type": true
}
],
"count": 1,
"meta": {
"curve_meaning": "recovery_curve nodes are percentage of NORMAL OPERATION over time after an event — business interruption, not building damage.",
"building_type": "Only fire, flood, heatwave and power_outage vary by building type. Every other hazard is a property of the location."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
building_type | Cost building type — what each means
| ||||||||||||||||||||||||
risk | Hazard — what each means
| ||||||||||||||||||||||||
recovery_curve.time_unit | Time unit — what each means
|
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 | string12 values — what each means
|
Address resolution works for every licensed country. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/geo/resolve?address=2500%20Edwards%20Dr%2C%20Fort%20Myers%2C%20FL"Response
Location, administrative area and flood zone.
Sample response to GET /v1/geo/resolve?address=Unter%20den%20Linden%201%2C%2010117%20Berlin&country=de (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"location": {
"address": "Unter den Linden 1, 10117 Berlin",
"matched": "Kommandantenhaus, 1, Unter den Linden, Friedrichswerder, Dorotheenstadt, Mitte, Berlin, 10117, Deutschland",
"country": "DE",
"lat": 52.5172077,
"lng": 13.3978344,
"state": "BE",
"county": null,
"county_fips": null,
"city": "Berlin",
"region": null,
"postcode": "10117",
"granularity": "address",
"approximate": false,
"flood_zone": "DE_none",
"in_sfha": null,
"flood_source": "BfG Hochwassergefahren- und -risikokarten (HWRM-RL reporting layers)",
"source": "OpenStreetMap / Nominatim + BfG HWRM"
},
"meta": {
"granularity": "A postcode-centroid match is not a rooftop match. Check `granularity` before using coordinates for anything boundary-sensitive."
}
}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 | string12 values — what each means
|
Only these five have a per-address hazard profile — see the coverage table above. Other countries return 400 naming the supported list. | ||||||||||||||||||||||||||
utility |
query | string |
US only. Names the electricity utility for outage statistics. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/risk/address?address=2500%20Edwards%20Dr%2C%20Fort%20Myers%2C%20FL"Response
Hazard levels with sources, confidence and attribution.
Sample response to GET /v1/risk/address?address=Unter%20den%20Linden%201%2C%2010117%20Berlin&country=de (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"location": {
"address": "Unter den Linden 1, 10117 Berlin",
"country": "DE",
"state": "BE",
"city": "Berlin",
"lat": 52.5172077,
"lng": 13.3978344,
"flood_zone": "DE_none"
},
"hazards": {
"flood": {
"level": "green",
"rating": "DE_none",
"value": "outside the mapped HQextrem footprint — ≈0.25%/yr",
"likelihood": "≈0.25% chance in any year that a mapped flood reaches this site",
"afreq": 0.0025,
"basis": "scenario band",
"confidence": "MEDIUM",
"source": "BfG Hochwassergefahren- und -risikokarten (HWRM-RL reporting layers)",
"sourceUrl": "https://geoportal.bafg.de/karten/HWRM_Aktuell/",
"asOf": "HWRM-RL reporting cycle",
"caveat": "Outside the mapped HQextrem footprint, which is not the same as safe. The July 2021 Ahr flood exceeded the mapped extreme footprint in the valley it devastated. The HWRM maps also cover river and coastal flooding only — heavy-rain (pluvial) flooding away from watercourses is not mapped nationally."
},
"heat": {
"level": "orange",
"value": "13 hot days/yr (Tmax ≥ 30 °C)",
"likelihood": "≈13 days a year above 30 °C",
"hotDaysPerYear": 13,
"confidence": "HIGH",
"source": "Deutscher Wetterdienst (DWD) — multi-annual hot days, 1 km grid",
"sourceUrl": "https://opendata.dwd.de/climate_environment/CDC/grids_germany/multi_annual/hot_days/",
"asOf": "DWD 1991-2020"
},
"wind": {
"level": "green",
"value": "2.2 m/s mean wind at 10 metres",
"likelihood": null,
"meanWindMs": 2.2,
"confidence": "LOW",
"caveat": "Exposure proxy. DWD publishes no gridded extreme-wind return periods, so this is the multi-annual MEAN wind field — it indexes how windy the location is, not how often it is stormed.",
"source": "Deutscher Wetterdienst (DWD) — mean wind at 10 metres, 1 km grid (exposure proxy)",
"sourceUrl": "https://opendata.dwd.de/climate_environment/CDC/grids_germany/multi_annual/wind_parameters/",
"asOf": "DWD 1981-2000"
},
"outage": {
"level": "green",
"value": "8.52 min/yr lost (Berlin)",
"likelihood": "≈8.52 minutes without power per year",
"saidiMin": 8.52,
"saidiMultiplier": 0.74,
"basis": "bundesland",
"basisLabel": "Berlin average",
"confidence": "HIGH",
"caveat": "A network operator whose territory spans several Bundesländer is attributed to one of them, so a Land figure is approximate at borders (BNetzA’s own note).",
"source": "Bundesnetzagentur — SAIDI_EnWG by Bundesland (2024)",
"sourceUrl": "https://www.bundesnetzagentur.de/DE/Fachthemen/ElektrizitaetundGas/Versorgungssicherheit/Versorgungsunterbrechungen/Auswertung_Strom/start.html",
"asOf": "BNetzA 2024"
},
"earthquake": {
"level": "green",
"rating": 0.0011,
"value": "0.001 g peak ground acceleration (1-in-475-year)",
"likelihood": "≈0.001 g shaking with a 10% chance in 50 years",
"confidence": "MEDIUM",
"basisLabel": "ESHM20 grid, on rock",
"caveat": "Ground motion on rock (Vs30 800 m/s), the only soil class the service publishes for this model — soft ground amplifies shaking, so a sediment site can exceed this. Banded on EN 1998-1’s recommended thresholds (very low ≤0.05 g, low ≤0.10 g); each National Annex may set its own.",
"source": "EFEHR — European Seismic Hazard Model 2020 (ESHM20), CC BY 4.0",
"sourceUrl": "https://doi.org/10.12686/a15",
"asOf": "ESHM20 (2020)"
},
"hail": {
"unavailable": true,
"why": "absent",
"source": "No queryable German hail climatology",
"caveat": "DWD publishes hail only as five-minute radar nowcasts (KONRAD3D), which cannot give an expected annual hail-day count. The KIT/ESSL radar climatology is research output, not a service. Hail stays at the national figure."
}
},
"attribution": "Contains data from Deutscher Wetterdienst (DWD) and Bundesanstalt für Gewässerkunde (BfG), DL-DE/BY-2.0.",
"meta": {
"coverage": "5 hazard(s) modelled for DE at this address, 1 could not be answered this time. A hazard that is absent entirely was never modelled for this country — that is not a finding of low risk.",
"caching": "Upstream answers are cached for 30 days, so repeated calls for one address are cheap and stable."
}
}Values in this response
| Field | Values | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
<hazard>.level | Hazard level — what each means
| ||||||||||
<hazard>.why | Hazard not answered — what each means
|
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 | string12 values — what each means
|
Countries with a sampled regional surface. | ||||||||||||||||||||||||||
hazard |
query | string |
Omit for every hazard in one payload. | ||||||||||||||||||||||||||
metric |
query | string |
US only — selects among the FEMA NRI measures. Ignored elsewhere. |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/risk/surface?country=de"Response
Per-region hazard values with units and method.
Sample response to GET /v1/risk/surface?country=de&hazard=flood (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"surface": {
"ok": true,
"country": "de",
"builtAt": "2026-09-26T20:57:02+00:00",
"method": "sample",
"points": 125,
"hazards": {
"flood": {
"unit": "%/yr",
"scaleKind": "ratio",
"method": "sample",
"quantity": null,
"source": null,
"nPresent": 13,
"nPoints": 125,
"areas": [
{
"code": "HB",
"mean": 0.35,
"max": 0.35,
"n": 6,
"occPerYear": null,
"ealPerYear": null,
"ealPerEvent": null
},
{
"code": "BB",
"mean": 0.35,
"max": 0.35,
"n": 1,
"occPerYear": null,
"ealPerYear": null,
"ealPerEvent": null
}
],
"areas_sample_note": "sample shortened: 5 items in the real response, 2 shown"
}
}
},
"meta": {
"resolution": "Values are per REGION, from a sampled lattice (or the FEMA census layer for the US) — not per address. For a specific building use GET /v1/risk/address.",
"metric": "Each region carries both `mean` (the average across its sample points) and `max` (the worst single point). A map shading \"could it happen here\" wants max; one shading \"what is it like here\" wants mean."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country | Country — what each means
| ||||||||||||||||||||||||||
hazards.<risk> | Hazard — what each means
|
Estimators
Running the model: applicable incentives, payback and ROI.
POST /v1/estimate/incentives estimate.incentives
Which incentives apply, and for how much
Not GET /v1/incentives with a filter, and the difference is the product. That endpoint answers what programmes exist in this territory. This one answers what would this building, doing this work, actually be paid — which needs the floor area, the ownership, the install date and the measures, because the amount is computed from them: a percentage of an eligible cost, a per-square-metre rate, a cap that bites at a certain size.
Three buckets, and two of them must never be added together.
available | Money this plan qualifies for now. The only figure in total_available. |
contingent | Real money that is event- or claim-triggered, or that somebody else must apply for — a community or pass-through programme is real money a building owner cannot claim. Also any programme whose rules do not record whether a public body (building.org_type local_government, state, federal, tribal) may apply, when the applicant is one — such a row carries applicant_recorded: false. Listed with the applicant named, and excluded from every total. |
| expired | Not returned at all, in any bucket. Not as a row with a flag: a caller who fetched one would cache it and quote it. |
There is deliberately no grand total on this response. The moment one exists somebody adds the contingent bucket to it, and an ROI is then built on money that is not the reader's to claim.
A paused programme appears in available with an amount of 0. Its funding has run out but it is still live, so you would likely qualify if funding returns — hiding it loses a real award. A zero cannot reach a payback figure, which is what stops it reaching an ROI.
Give an address if you have one: it changes the answer. State, county and municipal programmes are matched on where the building is. Without one only national schemes can apply, and meta.matched_on says so — a short list is not a finding that there is nothing available locally.
⚠️ Deadlines travel with the money. Any incentive that is closing soon carries a time_sensitivity object — it is not a flag, and it is absent entirely when there is nothing to say, so its presence means something:
"time_sensitivity": {
"level": "urgent",
"message": "74 days remaining — construction must begin before 2026-12-01.",
"ends": "2026-12-01"
}level | What it means |
|---|---|
urgent | The programme closes within 90 days. ends is the date; message is the sentence we show on screen. |
limited | Funding is finite, first-come, or a waitlist has opened. ends may be null — the constraint is money, not a date. |
⚠️ You will not see expired or will_expire on a priced row, and that is deliberate rather than an omission: a programme already closed by your planned installation date is not priced at all. It is absent from the response, because you cannot claim something that shuts before you install. If you expected a programme and do not see it, check planned_install_date.
The 90-day threshold is wider than it needs to be on purpose — warning early costs nothing, warning late costs the award — and it is the same threshold the AtlasAdapt screen badges with, so the two never disagree.
planned_install_date decides eligibility for the whole plan. Every upgrade is assumed installed on it, so one date drives incentive expiry, the date gates several programmes carry, and the tax date. Omit it and it defaults to today + 60 days — the same default the AtlasAdapt wizard puts in the box, so an API caller and someone reading the same building on screen are given the same answer.
⚠️ Null is not a neutral default here, which is why there is no way to send one. §48E, for example, only pays for property placed in service on or after 2025-01-01, and the engine refuses an incentive whose eligibility it cannot confirm — so an unspecified date would return a confident zero rather than an answer.
Each row carries the full stored definition, projected exactly as GET /v1/incentives projects it, so the incentives.eligibility, incentives.sources and incentives.funding field scopes apply here identically. A row whose amount comes from a country catalogue rather than the incentive database still appears, with definition: null and a note — dropping it would understate what the building can get.
Household income decides income-tied awards — and omitting it is an answer. Send household_income and household_size for a residential estimate. If either is missing the household is treated as the highest income band, so a grant reserved for lower incomes is not counted; nothing income-tied is ever booked on a guess. income says what was used — under estimate on /estimate/roi, at the top level on /estimate/incentives, and on each residential row of a portfolio:
"income": { "household_income": 40000, "household_size": 4, "band": "bleu", "category": "tres_modestes",
"scale": "FR_ANAH_IDF", "zone": "idf", "assumed_top": false, "needs": null,
"explanation": "Priced as the tres_modestes band on FR_ANAH_IDF." }Where the home is picks the table. France's Anah ceilings differ between Île-de-France and the rest of France; the address (its postcode or département) selects one, and scale / zone name it. The same household on €40,000 is très modestes in Paris and modestes in Lyon. In the US, ami_pct is the household's percentage of area median income.
Request
curl -X POST -H "Authorization: Bearer $ATLASADAPT_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"fr","segment":"commercial","building":{"type":"school","org_type":"local_government","floor_area":2000},"upgrades":["insulation","heatpump"]}' \
"https://api.atlasadapt.com/v1/estimate/incentives"Request body
| Field | Type | Notes |
|---|---|---|
country * | stringone of usdefrukchatdkesitnlnose | |
address | string | Optional, and only for us, de, ch, fr, uk. Include it to match sub-national programmes. |
segment | stringone of commercialresidential | Case-insensitive. Omitted: commercial. Any other value is a 400 — it is never quietly priced as commercial. |
building | object | Same shape as /v1/estimate/roi. For a home, year_built and current_heating_fuel reach the eligibility gates. |
building.year_built | stringone of unknownpre_19401940_19791980_19941995_19992000_20072008_20152016_plus | Residential. When the home was built. Several programmes require a minimum age (France's MaPrimeRénov' par geste: 15 years). Omitted: unknown, which such programmes accept and state as a condition — the same default the AtlasAdapt wizard uses. |
home_value | number | Residential only, and required there. |
upgrades | array | The measures you intend to install. Amounts are computed against these. |
planned_install_date | string | Filters to programmes open then. Omitted: today + 60 days, the AtlasAdapt wizard's default. |
household_income | number | Residential. The household's yearly income, in the country's currency, on the measure that country's income scale counts (France: the revenu fiscal de référence; US: gross household income). ⚠️ Omit it and the household is treated as the highest income band: help that depends on a lower income is not counted, and estimate.income.assumed_top is true. Send a JSON number, or a string of digits ("40000"); anything else — a blank string, true, an array, "1e5" — is a 400 rather than being read as €0. null means not given. |
household_size | integer | Residential. The number of people in the household. ⚠️ Income without a household size is treated the same as no income — the highest band — because every income ceiling depends on it. A whole number, or a string of digits; anything else is a 400. |
Response
Applicable incentives with computed amounts, and the contingent bucket kept separate.
Sample response to POST /v1/estimate/incentives (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"country": "FR",
"segment": "commercial",
"currency": "EUR",
"total_available": 70663,
"eligible_cost": null,
"available": [
{
"id": "beg_tertiary",
"name": "MaPrimeRénov Copropriétés / Tertiary renovation",
"amount": 55253,
"definition": {
"id": "fr:commercial:beg_tertiary",
"ref": "FR9",
"name": "MaPrimeRénov Copropriétés / Tertiary renovation",
"territory": "fr",
"mode": "commercial",
"grantor_id": "fr:fr_anah",
"grantor_type": "federal_national",
"grantor_name": "Anah (Agence nationale de l'habitat)",
"grantor_url": "https://www.anah.gouv.fr/",
"type": "grant",
"type_label": "Grant",
"amount_label": "MaPrimeRénov' Copropriétés — 30% of works (base)",
"amount_summary": "MaPrimeRénov' Copropriétés funds 30% of works (base), rising to 45% for deep renovation (≥50% energy gain), plus fragility/passoire bonuses. Reopened 23 Feb 2026 after a Jan-2026 suspension. Genuine tertiary/commercial buildings have no MPR equivalent.",
"is_cash": true,
"is_planning": false,
"is_annual": false,
"is_competitive": false,
"requires_ownership": false,
"claimable_by_owner": true,
"applicant": "owner",
"applicant_types": null,
"applicant_recorded": false,
"building_types": [
"restaurant",
"retail",
"office",
"warehouse",
"manufacturing",
"school",
"hospital",
"care_home",
"community_centre",
"sports_centre",
"emergency_services"
],
"upgrades": [
"heatpump",
"hvac_upgrade",
"roof",
"insulation",
"glazing",
"cool_roof",
"bms",
"led"
],
"measure_groups": [
"active_cooling",
"roof_covering",
"passive_cooling",
"building_controls"
],
"stacking": "stack",
"stacking_rule": "stackable_with_conditions",
"stacking_rules": [],
"stacking_notes": "Stackable with CEE commercial obligations and Éco-PTZ.",
"term_years": null,
"eligibility_summary": "Commercial/copropriété buildings; comprehensive renovation; energy audit required",
"source": {
"description": null,
"url": "https://www.anah.gouv.fr/",
"urls": [
{
"url": "https://www.anah.gouv.fr/",
"role": "programme",
"description": null,
"status": "unchecked"
}
],
"confidence": "MEDIUM",
"is_estimate": true
},
"active_2026": "YES",
"availability": {
"state": "open",
"counts_toward_roi": true,
"amount_available": null,
"guidance": null,
"because": null,
"cohort_dependent": false
},
"conditions": []
}
},
{
"id": "cee_tertiary",
"name": "CEE Tertiary (energy provider obligation)",
"amount": 12892,
"definition": {
"id": "fr:commercial:cee_tertiary",
"ref": "FR11",
"name": "CEE Tertiary (energy provider obligation)",
"territory": "fr",
"mode": "commercial",
"grantor_id": "fr:fr_edf",
"grantor_type": "federal_national",
"grantor_name": "EDF / Energy providers (CEE)",
"grantor_url": "https://www.economie.gouv.fr/particuliers/prime-energie-CEE",
"type": "grant",
"type_label": "Grant",
"amount_label": "Variable — calculated per kWhc saved. Typically €5,000-€50,000+ for commercial projects depending on scale.",
"amount_summary": null,
"is_cash": true,
"is_planning": false,
"is_annual": false,
"is_competitive": false,
"requires_ownership": false,
"claimable_by_owner": true,
"applicant": "owner",
"applicant_types": null,
"applicant_recorded": false,
"building_types": [
"restaurant",
"retail",
"office",
"warehouse",
"manufacturing",
"school",
"hospital",
"care_home",
"community_centre",
"sports_centre",
"emergency_services"
],
"upgrades": [
"heatpump",
"hvac_upgrade",
"roof",
"insulation",
"glazing",
"bms",
"led",
"air",
"cool_roof",
"night_purge",
"evap_cooling"
],
"measure_groups": [
"active_cooling",
"roof_covering",
"building_controls",
"passive_cooling"
],
"stacking": "stack",
"stacking_rule": "stackable_with_conditions",
"stacking_rules": [],
"stacking_notes": "Stackable with MaPrimeRénov commercial. Subject to total aid cap.",
"term_years": null,
"eligibility_summary": "Commercial buildings; via energy provider or aggregator; based on energy savings generated",
"source": {
"description": null,
"url": "https://www.economie.gouv.fr/particuliers/prime-energie-CEE",
"urls": [
{
"url": "https://www.economie.gouv.fr/particuliers/prime-energie-CEE",
"role": "programme",
"description": null,
"status": "unchecked"
}
],
"confidence": "LOW",
"is_estimate": true
},
"active_2026": "YES",
"availability": {
"state": "open",
"counts_toward_roi": true,
"amount_available": null,
"guidance": null,
"because": null,
"cohort_dependent": false
},
"conditions": []
}
}
],
"available_sample_note": "sample shortened: 3 items in the real response, 2 shown",
"contingent": [],
"stacking_rules": [],
"meta": {
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
},
"matched_on": "The country only — no address was given, so sub-national programmes could not be matched. A short list here is not a finding that there is nothing available locally.",
"buckets": "`available` is money this plan qualifies for now and is the only figure in `total_available`. `contingent` is real money that is event- or claim-triggered, or that somebody else must apply for — it is listed because hiding it loses a real award, and it is excluded from every total because counting it would invent one.",
"paused_programmes": "A programme whose funding has run out but which is still live appears in `available` with an amount of 0. That is deliberate: you would likely qualify if funding returns, so it is worth knowing about — and a zero cannot reach a payback figure.",
"expired_programmes": "Programmes that have ended are not returned at all, in any bucket.",
"amounts": "Computed by the same engine that prices a plan in /v1/estimate/roi, from the building you described. They are what this building would qualify for on today's published rules, not a headline rate."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
segment | Mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.territory | Country — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.mode | Incentive mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.type | Incentive type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.applicant | Applicant — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.applicant_types[] | Organisation (applicant) type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.building_types[] | Building type — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.upgrades[] | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.active_2026 | Programme status — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
definition.availability.state | Funding availability — what each means
|
POST /v1/estimate/roi estimate.roi
Payback, net cost and ROI
What it costs to harden one building, what that saves each year, and when it pays back — from the same engine that produces the figures in the AtlasAdapt product. A number you read here is the number we would show.
The address is optional, and the difference is large. Give one and the building is priced on its own hazards. Omit it and the building is priced on country averages — a legitimate question ("what would this cost anywhere in Germany?") and a materially different answer. meta.priced_on states which you got, every time. Per-address hazards are available for us, de, ch, fr and uk; sending an address for any other country is a 400 naming that list, rather than a silent fall back to averages.
Three cost figures, and they are not interchangeable.
| Field | What it is |
|---|---|
cost.gross | Before incentives. When cost.gross_known is false the country's tax treatment is unresolved and this equals cost.net_of_tax — totalling the two would double-count. |
cost.net_upfront | What you actually write a cheque for: gross, less incentives that apply today. |
cost.contingent_incentives | ⚠️ Shown, never subtracted. Money that is event- or claim-triggered, or that somebody else must apply for. It is reported because hiding it loses a real award, and it is deliberately not in net_upfront because counting it would invent one. |
non_cash_incentives lists the financing and non-cash policy programmes this building qualifies for — PACE, a property-tax exemption, a premium discount the state mandates — with incentive_class (financing or policy), status (eligible, or check where a condition we cannot test here applies, such as a jurisdiction list) and, where we can value it, annual_amount with term_years. priced: false means eligible but not valued. None of it is in any total.
to_confirm marks a figure to check before quoting it — on an upgrade (upgrades[].to_confirm) and on the payback (payback.to_confirm). Present only when there is something to confirm. Each entry is { code, text }: payback_under_1yr (the benefit rests on estimates more than any other figure), cost_converted (another country's price at the exchange rate), cost_unsourced (an estimated price with no published source yet), cost_outside_range (cost per area outside the measure's sourced range).
building.storeys prices every roof measure (roof area = floor area ÷ storeys × 1.10); omitted, it is the wizard's default for the building type (an office is 2).
payback.years may be null, and that is an answer — the plan does not pay back inside a service life we can defend. Branch on payback.classification, not on the null.
benefit.annual is a levelised average. Only the business-continuity leg escalates with climate risk; insurance and energy have no sourced escalator and are held flat. benefit.business_continuity_escalator_pct is published beside it rather than blended in, so you can draw the real shape instead of a straight line.
⚠️ Deadlines travel with the money. Any incentive that is closing soon carries a time_sensitivity object — it is not a flag, and it is absent entirely when there is nothing to say, so its presence means something:
"time_sensitivity": {
"level": "urgent",
"message": "74 days remaining — construction must begin before 2026-12-01.",
"ends": "2026-12-01"
}level | What it means |
|---|---|
urgent | The programme closes within 90 days. ends is the date; message is the sentence we show on screen. |
limited | Funding is finite, first-come, or a waitlist has opened. ends may be null — the constraint is money, not a date. |
⚠️ You will not see expired or will_expire on a priced row, and that is deliberate rather than an omission: a programme already closed by your planned installation date is not priced at all. It is absent from the response, because you cannot claim something that shuts before you install. If you expected a programme and do not see it, check planned_install_date.
The 90-day threshold is wider than it needs to be on purpose — warning early costs nothing, warning late costs the award — and it is the same threshold the AtlasAdapt screen badges with, so the two never disagree.
planned_install_date decides eligibility for the whole plan. Every upgrade is assumed installed on it, so one date drives incentive expiry, the date gates several programmes carry, and the tax date. Omit it and it defaults to today + 60 days — the same default the AtlasAdapt wizard puts in the box, so an API caller and someone reading the same building on screen are given the same answer.
⚠️ Null is not a neutral default here, which is why there is no way to send one. §48E, for example, only pays for property placed in service on or after 2025-01-01, and the engine refuses an incentive whose eligibility it cannot confirm — so an unspecified date would return a confident zero rather than an answer.
Ask for trace: true to receive the derivation. It requires the estimate.trace field scope; without that grant the estimate still returns and meta.trace says why the trace is absent.
Household income decides income-tied awards — and omitting it is an answer. Send household_income and household_size for a residential estimate. If either is missing the household is treated as the highest income band, so a grant reserved for lower incomes is not counted; nothing income-tied is ever booked on a guess. income says what was used — under estimate on /estimate/roi, at the top level on /estimate/incentives, and on each residential row of a portfolio:
"income": { "household_income": 40000, "household_size": 4, "band": "bleu", "category": "tres_modestes",
"scale": "FR_ANAH_IDF", "zone": "idf", "assumed_top": false, "needs": null,
"explanation": "Priced as the tres_modestes band on FR_ANAH_IDF." }Where the home is picks the table. France's Anah ceilings differ between Île-de-France and the rest of France; the address (its postcode or département) selects one, and scale / zone name it. The same household on €40,000 is très modestes in Paris and modestes in Lyon. In the US, ami_pct is the household's percentage of area median income.
Request
curl -X POST -H "Authorization: Bearer $ATLASADAPT_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"us","segment":"commercial","building":{"type":"office","floor_area":20000,"size":"small"},"upgrades":["generator","led"],"horizon_years":10}' \
"https://api.atlasadapt.com/v1/estimate/roi"Request body
| Field | Type | Notes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country * | stringone of usdefrukchatdkesitnlnose | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
address | string | Optional. Only for us, de, ch, fr, uk. Omit to price on country averages. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
segment | stringone of commercialresidential | Case-insensitive. Omitted: commercial. Any other value is a 400 — it is never quietly priced as commercial. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building | object | The building and who owns it. org_type and residential_type apply to both segments; the rest is commercial only. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.type | string | A building type this country offers — see GET /v1/countries — or a public building type (school, hospital, care_home, community_centre, sports_centre, emergency_services), or museum, university or agricultural. These are priced with the economics of their nearest modelled type, and estimate.building_proxy says which; their incentives are matched on the type you sent. museum, university and agricultural return no business_continuity leg. A site type (critical_infrastructure, infrastructure, natural_space, public_space) is a 400: it is matched, never priced. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.org_type | string9 values — what each means
| A public building has no business continuity: a public building type, or a public org_type on an office or warehouse (a town hall, a depot), returns NO business_continuity leg, and estimate.business_continuity says why. Who is applying — reaches every eligibility gate. A public body (local_government, state, federal, tribal) is accepted on office, warehouse and the public building types. Omitted: commercial, or homeowner for a residential estimate. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.residential_type | string22 values — what each means
| Residential only. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.current_heating_fuel | stringone of gasoilcoalelectricdistrictheatpumpotherunknown | Residential. The fuel a heat pump would replace. A heat pump's saving depends almost entirely on it: against gas it is a small cost in the UK (about £93 a year more to run at 2025 tariffs), and a saving of about €650 in France, €125 in Germany and €219 in Italy. Only gas has been researched; for any other fuel the national catalogue figure stands. Default: unknown, priced as gas. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.commercially_insured | boolean | Public buildings only. Most public bodies are pooled or self-insured, and a pool does not reprice property for a retrofit, so by default a public building earns no premium discount and keeps every avoided loss. Default: true for a UK or Swedish council, false for every other public body. Send true if a commercial insurer covers the building. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.floor_area | number | In the country's own unit. Omitted, a researched default for the type and size is used. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.size | stringone of smallmediumlarge | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.owns | boolean | ⚠️ Send false for a tenant. Absent reads as an owner, and owner-only grants would be offered. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.heat_profiles | array | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.year_built | stringone of unknownpre_19401940_19791980_19941995_19992000_20072008_20152016_plus | Residential. When the home was built. Several programmes require a minimum age (France's MaPrimeRénov' par geste: 15 years). Omitted: unknown, which such programmes accept and state as a condition — the same default the AtlasAdapt wizard uses. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.storeys | integer | Storeys above ground. Prices every roof measure: roof area = floor area ÷ storeys × 1.10. Omitted → the default for the building type (office 2, others 1). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building.historic_designation | stringone of nonenational_register_listedcontributing_in_districtstate_landmarklocal_designationunknown | Official historic designation — designated, not merely old. Reaches the eligibility gates of historic-rehabilitation credits and exemptions. Omit when not known; unknown is also accepted. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
home_value | number | Residential only, and required there. Every avoided-damage figure is a fraction of it. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
household_income | number | Residential. The household's yearly income, in the country's currency, on the measure that country's income scale counts (France: the revenu fiscal de référence; US: gross household income). ⚠️ Omit it and the household is treated as the highest income band: help that depends on a lower income is not counted, and estimate.income.assumed_top is true. Send a JSON number, or a string of digits ("40000"); anything else — a blank string, true, an array, "1e5" — is a 400 rather than being read as €0. null means not given. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
household_size | integer | Residential. The number of people in the household. ⚠️ Income without a household size is treated the same as no income — the highest band — because every income ceiling depends on it. A whole number, or a string of digits; anything else is a 400. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrades | array | Measure ids — see GET /v1/upgrades. Ids this building does not offer come back in unavailable_upgrade_ids rather than being silently dropped. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
horizon_years | integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hazard | string | Attribute the result to one peril. Turns off every benefit leg that cannot be attributed to it. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
planned_install_date | string | Filters incentives to what is open then, and sets the tax date. Omitted: today + 60 days, the AtlasAdapt wizard's default. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
trace | boolean | Requires the estimate.trace field scope. |
Response
The priced plan, with meta.priced_on stating whether it used the address or country averages.
Sample response to POST /v1/estimate/roi (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"estimate": {
"country": "US",
"currency": "USD",
"segment": "commercial",
"horizon_years": 10,
"hazard": null,
"upgrades": [
{
"id": "generator",
"name": "Standby generator (server / critical loads)",
"cost": 24357,
"insurance_saving": 0,
"energy_saving": 0
},
{
"id": "led",
"name": "LED + smart lighting",
"cost": 18981,
"insurance_saving": 0,
"energy_saving": 5110
}
],
"unavailable_upgrade_ids": [],
"cost": {
"gross": 43338,
"gross_known": false,
"net_of_tax": 43338,
"tax": 0,
"incentives": 0,
"net_upfront": 43338,
"contingent_incentives": 0
},
"benefit": {
"annual": 6358,
"recurring_cost": 1200,
"business_continuity_escalator_pct": 2,
"legs": {
"business_continuity": 1248,
"insurance": 0,
"loss_reduction": 0,
"energy": 5110
}
},
"payback": {
"years": 8.402093834819697,
"classification": "investment",
"fully_funded": false
},
"horizon": {
"net": 8242,
"ratio": 0.19017951912870923,
"years_earning": 10,
"service_life_years": null
},
"incentives": [],
"planning_incentives": []
},
"meta": {
"priced_on": "Country averages — no address was given, so this is what a building of this type and size would cost and save anywhere in US, not at a location.",
"engine_ms": 491,
"trace": "not requested",
"incentives": "Amounts are what this plan would qualify for on today's published rules. `contingent_incentives` is money that is event- or claim-triggered, or that somebody else must apply for: it is shown because hiding it loses a real award, and it is NOT in `net_upfront` because counting it would invent one.",
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
}
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
segment | Mode — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrades[].id | Upgrade — what each means
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payback.classification | Payback classification — what each means
|
POST /v1/estimate/supplychain estimate.supplychain
Downstream dependency exposure
When this building stops, who else stops, and for how long?
A sole-source manufacturing or warehouse site carries a loss far larger than its own. This traces it: the site's downtime under one hazard, against the customer's stock buffer and how long it takes them to qualify an alternative source.
stopped days S = max(0, min(D, L) − B)
downstream S × (annual shipment value × dependency leverage) / 365min(D, L) is the model, not a safety clamp: your customer restarts when either you restart or they have qualified someone else, whichever comes first. This is the Novelis/Porsche mechanism — the flood was not the problem, re-qualifying specialty aluminium outside Europe taking quarters was.
⚠️ The downstream figure is your customer's money, not yours. On standard force-majeure terms you would not bear it. It is reported because it is the reason your customer cares whether this building is hardened — and there is no field in this response that sums it with anything. Every figure carries a bearer; the contractual slice, if you supply terms, is a third figure and is not summed either. A total would assert a liability that may not exist.
⚠️ This is ONE event, not an annual average. scenario.probability_pct is how likely that event is in a year. A scenario quoted without its likelihood reads as a prediction.
The restart tail is asked for and never invented. That is the time to re-commission and re-qualify after the building itself is usable, and for a sole-source line it is often the largest part of the answer. We hold no default for it, so if you do not send restart_tail_days it is absent, not zero — and because nobody has ruled whether a given hazard's closure period already includes re-equipping time, a tail you do send is reported separately and not added to the downtime. downtime.closure_basis_note says so on every response.
Buffer and lead time fall back to our researched per-vertical defaults when you omit them, and the response says which figures rest on them (chain.buffer_is_our_default, meta.illustration). A prefill becomes a measurement by being displayed, so it is labelled.
⚠️ An implausible dependency leverage is refused, not returned. Above 100x we will not state the figure without confirmation: the response is a 422 carrying the computed leverage and an acknowledge_leverage key. Re-send with that key and the answer comes back unchanged. On screen this is a prompt; over an API there is nobody to prompt, and publishing a number our own model calls implausible is worse than asking twice.
Would their insurance pay? Usually far less than the reader assumes — and that gap is the argument.
insurance.insurer and insurance.uncovered are a split of downstream.amount — they sum to it and to nothing else, and neither is ever added to contractual, which is your money. That is the fourth bearer: owner · counterparty · insurer · uncovered.
Contingent business interruption is a different product from the BI cover on your own building. It responds to damage at someone else's property, and insurance.gates walks the conditions in the order an adjuster reaches them:
| Gate | Why it so often shuts |
|---|---|
physical_damage | A standard form needs the dependent property to be damaged. A grid failure stops the line and breaks nothing — we can tell you this one without seeing any policy, and for such a peril insurer is a confident zero. |
scheduled_property | Cover extends only to dependent properties named on the schedule. A customer with sound cover who never listed this site has none for it — the quietest reason a downstream loss turns out uninsured. |
waiting_period | Typically 24–72 hours, removing the first day or more of any claim. |
sublimit | Standard-form contingent sublimits are frequently a small fraction of a loss this size. |
tier_2 | Rarely reached. A schedule names direct dependents; your customer's supplier is usually outside it. |
⚠️ Where we have not been told a term, the amounts are null — not zero. A zero would read as a finding that we had checked. insurance.coverage_known is false in that case and every gate is still listed, as the questions to put to your customer. Send cbi_scheduled, cbi_waiting_period_hours and cbi_sublimit and we will split the figure.
⚠️ insurance.blocked_by names a gate that is definitively shut. When it is set, insurer is zero with confidence and the whole downstream figure sits with your customer, uninsured.
Tier 2 is assessed on its own gates, never by reusing tier 1's answer.
Pair it with /v1/estimate/roi: this says what the exposure is, that says what removing it costs and when it pays back.
Request
curl -X POST -H "Authorization: Bearer $ATLASADAPT_KEY" \
-H "Content-Type: application/json" \
-d '{"country":"us","building_type":"manufacturing","building_size":"medium","floor_area":40000,"vertical":"automotive_components","site_annual_revenue":40000000,"share_of_output_pct":35,"customer_revenue_gated":600000000}' \
"https://api.atlasadapt.com/v1/estimate/supplychain"Request body
| Field | Type | Notes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
country * | stringone of usdefrukchatdkesitnlnose | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_type * | string22 values — what each means
| Only manufacturing or warehouse — the building types with a supply chain to break. Anything else, or a public body (org_type), is refused with invalid_request: "invalid organization type / building type - must be a manufacturing or warehouse building run by a commercial or nonprofit organization". | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
org_type | string9 values — what each means
| Who runs the site. A public body (local_government, state, federal, tribal, public_housing_body) is refused: a public building has no business continuity to cascade. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
building_size | stringone of smallmediumlarge | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
floor_area | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
site_annual_revenue * | number | ⚠️ Required, and never defaulted — every downstream figure is a fraction of it. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
vertical | string | Selects the researched buffer and lead-time defaults. other when unsure. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
share_of_output_pct | number | What share of this site's output goes to the customer in question. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_revenue_gated | number | The customer revenue this input gates — a small casting can stop a large vehicle line. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
substitution_lead_days | number | How long your customer needs to qualify an alternative source. Omitted, our per-vertical default is used and labelled. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
buffer_days | number | Stock your customer holds. Below it, nothing downstream stops. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
restart_tail_days | number | Re-commissioning and re-qualification after the building is usable. No default — absent, never zero. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hazard | string | Omit for the site's most likely hazard. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upgrades | array | Hardening measures in place, which shorten the site downtime. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
horizon_years | integer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
liquidated_damages_per_day | number | Contract terms. Produces a third, owner-bearing figure — still never summed. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
liquidated_damages_cap | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
force_majeure_excuses | boolean | Whether your contract excuses these damages. Default true, which is the usual case. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tier2_buffer_days | number | The end producer beyond your direct customer. Absent, no tier 2 is reported — never extrapolated. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tier2_substitution_lead_days | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
acknowledge_leverage | string | The key returned by a 422 when the implied leverage exceeds 100x. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cbi_scheduled | boolean | Is this site named as a scheduled dependent property on your customer's policy? Omitted, we report the question rather than assume an answer. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cbi_waiting_period_hours | number | Their contingent BI waiting period. Removes the first hours of any claim. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cbi_sublimit | number | Their contingent BI sublimit — frequently a small fraction of a loss this size. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cbi_covers_tier2 | boolean | Does their schedule extend beyond the direct supplier? Rarely. |
Response
The cascade, with every figure attributed to whoever bears it.
Sample response to POST /v1/estimate/supplychain (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"assessment": {
"country": "US",
"building_type": "manufacturing",
"vertical": "automotive_components",
"scenario": {
"hazard": "hurricane",
"label": "Hurricane",
"probability_pct": 6.14,
"events_per_year": null
},
"downtime": {
"site_days": 55,
"closure_days": 55,
"restart_tail_days": null,
"restart_tail_included": false,
"restart_tail_shown_separately": false,
"restart_tail_unstated": true,
"closure_basis": "unknown",
"closure_basis_note": "Nobody has ruled whether this hazard's closure period already includes time to re-equip, so your restart tail is reported separately and is NOT added to the downtime. Adding it could double-count; dropping it would understate a sole-source site."
},
"chain": {
"substitution_lead_days": 84,
"substitution_lead_is_our_default": true,
"buffer_days": 36,
"buffer_is_our_default": true,
"stopped_days": 19
},
"downstream": {
"bearer": "counterparty",
"amount": 31232877,
"basis": "industry_default",
"annual_shipment_value": 14000000,
"leverage": 42.86,
"ratio_to_on_site_loss": 11.4,
"on_site_loss": 2739726
},
"insurance": {
"insurer": {
"bearer": "insurer",
"amount": null
},
"uncovered": {
"bearer": "uncovered",
"amount": null
},
"coverage_known": false,
"blocked_by": null,
"gates": [
{
"id": "physical_damage",
"passed": true,
"why": "This peril physically damages the site, which is the trigger a standard contingent BI form is written against."
},
{
"id": "scheduled_property",
"passed": null,
"why": "Unknown: contingent cover usually responds only for dependent properties named and scheduled on the policy. Ask your customer whether this site is listed."
}
],
"gates_sample_note": "sample shortened: 4 items in the real response, 2 shown"
},
"tier2": null,
"contractual": {
"bearer": "owner",
"amount": null,
"excused_by_force_majeure": true,
"capped": false
}
},
"meta": {
"whose_money": "The downstream figure is your CUSTOMER'S revenue at risk, not yours. On standard force-majeure terms you would not bear it — your exposure is the contract, not the damages. It is reported because it is the reason your customer cares whether this building is hardened, and it is deliberately not added to anything.",
"no_total": "There is no field here that sums the downstream and contractual figures. They have different bearers, and a total would assert a liability that may not exist. `insurance.insurer` and `insurance.uncovered` are a SPLIT of `downstream.amount` — they sum to it and to nothing else.",
"scenario_only": "This is ONE event, not an annual average. `scenario.probability_pct` is how likely that event is in a year — a scenario quoted without its likelihood reads as a prediction.",
"illustration": "ILLUSTRATION, NOT AN ESTIMATE: the customer's stock buffer and the substitution lead time came from our researched default for this vertical, not from you. Send `buffer_days` and `substitution_lead_days` for a figure about your actual chain.",
"restart_tail": "You did not state a process restart tail — the time to re-commission and re-qualify after the building itself is usable. We hold no default for it and will not invent one, so it is absent rather than zero. For a sole-source line it is often the largest part of the answer.",
"insurance": "We cannot say how much of this your customer's insurance would pay, and we are not guessing — the amounts are null rather than zero because we have not checked. Contingent business interruption is a DIFFERENT product from ordinary BI, and it turns on terms only they hold. `insurance.gates` lists the questions to ask them. Send `cbi_scheduled`, `cbi_waiting_period_hours` and `cbi_sublimit` and we will split the figure."
}
}Values in this response
| Field | Values | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
building_type | Cost building type — what each means
| ||||||||||||||||||||||||
scenario.hazard | Hazard — what each means
| ||||||||||||||||||||||||
*.bearer | Who bears the loss — what each means
|
POST /v1/estimate/portfolio estimate.portfolio
ROI across many sites (asynchronous)
Price a whole property book in one call. This endpoint is asynchronous: it answers 202 with a job id, and you poll GET /v1/estimate/portfolio/{id} until the job is done.
Why it is not synchronous. Pricing a building takes milliseconds. Resolving its address takes about two seconds of real network across the hazard sources, so a hundred buildings is roughly three and a half minutes and four hundred is about thirteen. Nothing should hold an HTTP connection open for that. Answers are cached for 30 days, so a repeat of the same portfolio is dramatically quicker.
Give every site a ref, and match results by it — never by array position. Results come back in submission order, but a ref survives anything that order does not.
A site that cannot be priced does not fail the portfolio. Three unresolvable addresses out of four hundred is a normal upload: those three rows come back with ok: false and their own error, the other 397 are complete, and summary.failed counts them. Check it before totalling a column.
defaults applies to every site, and any site may override any of it — so a book of four hundred buildings in one country, all considering the same measures, is a short document.
⚠️ What it costs. A portfolio counts as one request per site against your monthly limit — the same as calling /v1/estimate/roi once per building, because that is the work done. It is charged at submission and stated in meta.quota on the way in. Polling is free. If the batch would exceed your remaining allowance the whole submission is refused with the figures, rather than half-completed.
Three limits, and each one refuses clearly rather than degrading quietly.
| Limit | Default | What you get when you cross it |
|---|---|---|
| Sites per portfolio | 500, or your key's max_batch if lower | 400 naming max_batch and the number you sent |
| Portfolios queued or running at once | 3 per customer | 429 with error.in_flight and error.max_in_flight, and Retry-After: 60. Wait for one to finish — it is not a quota problem and no allowance was spent |
| Monthly allowance | one request per site | 429 with error.this_request_would_cost. The submission is refused whole, never half-run |
⚠️ Those two 429s mean different things and carry different fields. One says too many jobs at once, one says not enough allowance left, and the generic burst limiter says too many requests this minute. Branch on error.code and the fields above, not on the status alone.
How long a job takes, concretely. The compute is not the cost — address resolution is, at about 2 s per building the first time we see it, cached for 30 days after:
| 100 sites | 400 sites | |
|---|---|---|
no address on any site (priced on country averages) | ~1.4 s | ~3.3 s |
every site with a new address | ~3.5 min | ~13 min |
| addresses we have seen in the last 30 days | seconds | under a minute |
Retention: 7 days, or a 10 MB ceiling across all stored results — whichever comes first. A finished job's request and results are deleted at expires_at, and may go sooner, oldest first, if total stored results reach the ceiling. Polling an expired job tells you which happened, because only one of them is worth changing your integration over. A queued or running job is never removed by the ceiling. Download your results; this is not storage.
Totals are per currency, never across them. A portfolio holding US and German buildings gets a by_currency block; there is no FX rate in this model and inventing one here would be a rate nobody sourced.
concentration is the point of asking about a portfolio rather than a building. A book with one catastrophic site and one with four hundred mediocre ones have the same total and completely different decisions attached, so the answer ranks sites by net benefit at horizon and reports what share sits in the top 1, 5 and 10 — plus how many sites do not pay back at all.
Request
curl -X POST -H "Authorization: Bearer $ATLASADAPT_KEY" \
-H "Content-Type: application/json" \
-d '{"defaults":{"country":"us","upgrades":["generator","led"],"horizon_years":10},"sites":[{"ref":"HQ","building":{"type":"office","floor_area":20000}},{"ref":"PLANT-1","building":{"type":"manufacturing","floor_area":80000,"size":"large"}}]}' \
"https://api.atlasadapt.com/v1/estimate/portfolio"Request body
| Field | Type | Notes |
|---|---|---|
defaults | object | Applied to every site; any site may override any field. Same shape as a site. ⚠️ A site that sends household_income: null overrides the default — its household is unknown, so it is priced as the highest income band; only a site that OMITS the field inherits the default. |
sites * | array | Up to 500 per portfolio, or your key's max_batch if it is lower. |
Response
Accepted. job.poll_url is where the answer will appear; Location carries the same URL.
Sample response to POST /v1/estimate/portfolio (HTTP 202), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"job": {
"id": "job_683e2a90956121d7b9377d3d261ef01c",
"status": "queued",
"sites": {
"total": 2,
"completed": 0,
"failed": 0
},
"created_at": "2026-09-26T20:57:04+00:00",
"started_at": null,
"finished_at": null,
"expires_at": "2026-10-03T20:57:04+00:00",
"poll_url": "https://api.atlasadapt.com/v1/estimate/portfolio/job_683e2a90956121d7b9377d3d261ef01c"
},
"meta": {
"status": "Accepted. Poll `job.poll_url` until `job.status` is `done`.",
"poll_after_seconds": 10,
"estimated_seconds": 4,
"why_it_takes_that_long": "Pricing is milliseconds per building; resolving an address is about two seconds of real network across the hazard sources, and answers are cached for 30 days — so a repeat of this portfolio will be far quicker than the first run.",
"quota": "This portfolio counts as 2 request(s) against your monthly limit — one per site, the same as calling /v1/estimate/roi 2 times.",
"matching": "Give each site a `ref` and match results by it. Results are returned in submission order, but a `ref` survives anything that order does not."
}
}Values in this response
| Field | Values | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
status | Job status — what each means
|
GET /v1/estimate/portfolio/{id} estimate.portfolio
Poll a portfolio job
The status of a submitted portfolio, and its results once it is done.
Polling is free — it does not count against your monthly limit. Come back after meta.poll_after_seconds (also sent as Retry-After); polling in a tight loop will hit the burst limiter, and a 429 is not the job failing.
job.status is one of:
queued | accepted, waiting for a worker |
running | in progress — job.sites.priced and job.sites.failed advance as it goes |
done | finished. summary, concentration and sites are present |
failed | produced no answer at all; see job.error. Individual sites that could not be priced do not cause this |
expired | it completed, and the results have since been deleted under the retention policy. Resubmit to run it again |
⚠️ expired and not found are deliberately different answers: one tells you to resubmit, the other sends you looking for a typo that is not there.
Results are deleted after job.expires_at. A portfolio is your commercial information — every building you own, with its address — and it is not ours to hold indefinitely. Download what you need.
An id that is not yours answers exactly as an id that does not exist, so this endpoint cannot be used to discover which job ids are real.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id * |
path | string |
Request
curl -H "Authorization: Bearer $ATLASADAPT_KEY" \
"https://api.atlasadapt.com/v1/estimate/portfolio/job_9f2c1a7b4e6d8035f1a2b3c4d5e6f708"Response
Job status, and the results once complete.
Sample response to GET /v1/estimate/portfolio/job_683e2a90956121d7b9377d3d261ef01c (HTTP 200), captured from the
gateway on 2026-09-26 with a metadata key. Filters keep it to one short page, and any list
longer than two items is shortened, with a marker saying how many there were.
{
"ok": true,
"job": {
"id": "job_683e2a90956121d7b9377d3d261ef01c",
"status": "done",
"sites": {
"total": 2,
"completed": 2,
"failed": 0
},
"created_at": "2026-09-26T20:57:04+00:00",
"started_at": "2026-09-26T20:57:04+00:00",
"finished_at": "2026-09-26T20:57:05+00:00",
"expires_at": "2026-10-03T20:57:04+00:00"
},
"summary": {
"sites": 2,
"priced": 2,
"failed": 0,
"by_currency": {
"USD": {
"sites": 2,
"gross": 164344,
"incentives": 0,
"net_upfront": 164344,
"annual_benefit": 59120,
"net_at_horizon": 402856,
"contingent_incentives": 0
}
}
},
"concentration": {
"basis": "net benefit at horizon, ranked across every priced site",
"sites_ranked": 2,
"top_1_pct_of_benefit": 98,
"top_5_pct_of_benefit": 100,
"top_10_pct_of_benefit": 100,
"top_sites": [
{
"ref": "PLANT-1",
"index": 1,
"address": null,
"currency": "USD",
"net_at_horizon": 394614,
"payback_years": 2.3468057872076336
},
{
"ref": "HQ",
"index": 0,
"address": null,
"currency": "USD",
"net_at_horizon": 8242,
"payback_years": 8.402093834819697
}
],
"sites_negative_at_horizon": 0,
"sites_that_never_pay_back": 0,
"sites_accounted_for": 2,
"partition_note": "ranked + negative + never = every priced site. A site can be negative at your horizon and still pay back after it; lengthening the horizon moves it."
},
"sites": [
{
"ref": "HQ",
"index": 0,
"ok": true,
"address": null,
"country": "US",
"currency": "USD",
"priced_on": "country_averages",
"cost": {
"gross": 43338,
"gross_known": false,
"incentives": 0,
"net_upfront": 43338,
"contingent_incentives": 0
},
"benefit": {
"annual": 6358,
"recurring_cost": 1200
},
"payback": {
"years": 8.402093834819697,
"classification": "investment"
},
"horizon": {
"net": 8242,
"ratio": 0.19017951912870923
},
"unavailable_upgrade_ids": []
},
{
"ref": "PLANT-1",
"index": 1,
"ok": true,
"address": null,
"country": "US",
"currency": "USD",
"priced_on": "country_averages",
"cost": {
"gross": 121006,
"gross_known": false,
"incentives": 0,
"net_upfront": 121006,
"contingent_incentives": 0
},
"benefit": {
"annual": 52762,
"recurring_cost": 1200
},
"payback": {
"years": 2.3468057872076336,
"classification": "investment"
},
"horizon": {
"net": 394614,
"ratio": 3.2611110192883
},
"unavailable_upgrade_ids": []
}
],
"meta": {
"status": "Complete.",
"retention": "Results are kept until `expires_at` — 7 days — and then deleted, because a portfolio is your commercial information and not ours to hold indefinitely. They may also be removed sooner if total stored results across all customers reach our 10 MB ceiling, oldest first. Download what you need rather than polling for it later.",
"contract": {
"disclaimer": "Unless otherwise stated in your contract the data here is © 2026 Atlas Adapt. All information is provided as guidance and should be confirmed with the grantor of the incentive before applying.",
"expired_excluded": "Programmes that have ended are never returned.",
"paused_shown_not_counted": "Incentives with availability.counts_toward_roi = false are real programmes whose funding is currently paused. Show them to your user with the stated guidance; do not include them in any payback, net cost or ROI total.",
"contingent": "Incentives with claimable_by_owner = false are not applicable for by the building owner. Attribute them to the named applicant; never add them to an owner's available funding.",
"conditions_must_be_displayed": "conditions[] are eligibility criteria the programme imposes that cannot be checked from the data (for example \"standard HVAC replacements are ineligible\"). Amounts assume they are met. Wherever you show the incentive, show its conditions beside it — a condition with upgrades lists only those upgrades, so show it when one of them is part of what you display. Pass ?lang= (fr, de, it, nl, es, da, nb, sv) for translated text; text_en is always the original."
}
}
}Values in this response
| Field | Values | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
status | Job status — what each means
| ||||||||||||
payback.classification | Payback classification — what each means
|
Vocabularies
Every enumerated value the API accepts or returns, with what it means.
Country
The country parameter, case-insensitive.
| Value | Description |
|---|---|
us | United States |
uk | United Kingdom — also accepted as GB (ISO 3166-1), any case |
de | Germany |
fr | France |
it | Italy |
es | Spain |
nl | Netherlands |
at | Austria |
ch | Switzerland |
dk | Denmark |
no | Norway |
se | Sweden |
Mode
Which segment an incentive or estimate serves.
| Value | Description |
|---|---|
residential | Homes, and the people who own or live in them. |
commercial | Businesses, public bodies and every non-residential building. |
Organisation (applicant) type
org_type on GET /v1/incentives (alias applicant_type), building.org_type in the estimators, and the values in each incentive's applicant_types. null in applicant_types means not yet recorded — never "everyone".
| Value | Description |
|---|---|
commercial | A private business applying on its own account. |
nonprofit | A charity or other tax-exempt body. Stored as a flag beside commercial, so a programme open to businesses is not assumed open to charities, and vice versa. |
local_government | A municipality or local authority — commune, Gemeinde, comune, ayuntamiento, kommun, city, county. |
state | The intermediate tier of government: a US state, German Land, French région or département, Italian regione, Spanish comunidad autónoma. |
federal | National government and its agencies. |
tribal | A US tribal government. United States only. |
homeowner | A household applying for work on its own home. The default applicant for a residential request. |
public_housing_body | A social landlord: public housing authority, bailleur social, housing association. |
owners_association | The owners of a building held in co-ownership, acting together for its common parts: a condominium association or HOA (US), syndicat des copropriétaires (FR), WEG (DE), comunidad de propietarios (ES), condominio (IT). |
Building type
building_type on GET /v1/incentives, building.type in the estimators, and each incentive's building_types. One dimension, no subtypes: who owns the building is org_type. The four site types (critical_infrastructure, infrastructure, natural_space, public_space) are not inherited by every non-residential programme: they return only programmes whose rules name them, so today they return few or none. The third column is the building type whose costs and continuity the estimators price it as.
| Value | Description | Priced as |
|---|---|---|
single_family | A detached or semi-detached house. | residential |
townhouse | A terraced or row house with its own roof section. | residential |
condo | A flat or apartment within a larger building. | residential |
multifamily | A whole residential building of several dwellings — including social housing, with org_type=public_housing_body. | residential |
restaurant | A restaurant or café. Priced as retail, with the hot-kitchen heat exposure on. | retail |
retail | A shop or other retail premises. | retail |
office | An office — and a town hall or civic offices, sent with a public org_type. | office |
warehouse | A warehouse, logistics or storage building — and a municipal depot or works yard, sent with a public org_type. | warehouse |
manufacturing | Light manufacturing or a workshop. | manufacturing |
school | A school. | office (proxy — no school model yet; incentives are matched on school) |
hospital | A hospital or clinic. | office (proxy — no hospital model yet; incentives are matched on hospital) |
care_home | A care or nursing home. | office (proxy — no care_home model yet; incentives are matched on care_home) |
community_centre | A community centre, library or civic assembly hall. | office (proxy — no community_centre model yet; incentives are matched on community_centre) |
sports_centre | A sports hall or swimming pool. | office (proxy — no sports_centre model yet; incentives are matched on sports_centre) |
emergency_services | A fire, police or ambulance station. | office (proxy — no emergency_services model yet; incentives are matched on emergency_services) |
museum | A museum, gallery or cultural complex. | office (proxy — no museum model yet, and no business continuity; incentives are matched on museum) |
university | A university or higher-education campus. | office (proxy — no university model yet, and no business continuity; incentives are matched on university) |
agricultural | Farm outbuildings, barns, yards and service areas. The farmhouse itself is single_family. | office (proxy — no agricultural model yet, and no business continuity; incentives are matched on agricultural) |
critical_infrastructure | A site, not a building: substation, pumping or water-treatment site, gas station or compressor, telecom facility, data center. Returns only programmes that name this type. | not priced (a site: matching only — the estimators refuse it) |
infrastructure | A site, not a building: transport hub or terminal, corridor, bridge, tunnel, pipeline, buried service or utility route. Returns only programmes that name this type. | not priced (a site: matching only — the estimators refuse it) |
natural_space | A site, not a building: meadow, grassland, heath, woodland, wetland, dune system. Returns only programmes that name this type. | not priced (a site: matching only — the estimators refuse it) |
public_space | A site, not a building: a square, park or outdoor sports ground. Returns only programmes that name this type. | not priced (a site: matching only — the estimators refuse it) |
Cost building type
building_type on GET /v1/costs and GET /v1/climate/params — the priced economics, a coarser list than the building type above. A school's costs are an office's until it has its own model.
| Value | Description |
|---|---|
office | The office cost and continuity model. |
retail | The retail cost and continuity model. |
warehouse | The warehouse cost and continuity model. |
manufacturing | The manufacturing cost and continuity model. |
residential | Any home. |
Measure group
The measure_groups parameter on GET /v1/incentives (one or several, comma-separated), and each incentive's measure_groups. A functional category of adaptation work, derived from the measures a programme funds — so you can ask "what funding exists for keeping water out?" without knowing our upgrade codes.
A programme that funds only energy efficiency belongs to no group, so filtering by any group excludes energy-only schemes while keeping those that fund both.
⚠️ Coverage is not uniform. asset_elevation and wet_floodproofing are real categories for which AtlasAdapt holds no measure, so they always return an empty page; others are mapped but funded by no live programme in a given country. Read an empty result as "none known here", not as an error.
Groups marked provisional are working categories that may be renamed; the flood groups are settled.
| Value | Hazard | Description |
|---|---|---|
flood_exclusion | Flood | Floodwater exclusion: barriers and closures |
envelope_sealing | Flood | Building-envelope sealing against water ingress |
backflow_control | Flood | Reverse-flow control on drains and sewers |
water_removal | Flood | Active removal of floodwater |
site_drainage | Flood | Site drainage and runoff conveyance |
building_elevation | Flood | Raising the building or its lowest floor |
asset_elevation | Flood | Raising equipment, services and stock |
wet_floodproofing | Flood | Damage-tolerant interiors for water that gets in |
flood_structural | Flood | Structural flood-load management |
source_control | Flood | Site-scale source control (SuDS) |
roof_covering | Other — provisional | Roof covering & roof-to-wall connections |
opening_protection | Other — provisional | Opening protection (windows, doors, shutters) |
ember_resistance | Other — provisional | Ember & ignition resistance |
vegetation_management | Other — provisional | Vegetation management / defensible space |
fire_suppression | Other — provisional | Fire suppression |
seismic_structural | Other — provisional | Seismic structural retrofit |
seismic_restraint | Other — provisional | Seismic non-structural restraint |
roof_structure | Other — provisional | Structural roof reinforcement |
backup_power | Other — provisional | Backup power & storage |
active_cooling | Other — provisional | Active cooling |
passive_cooling | Other — provisional | Passive cooling & heat reduction |
building_controls | Other — provisional | Building controls & monitoring |
Incentive type
Each incentive's type. type_label carries the programme's own wording.
| Value | Description |
|---|---|
grant | Money paid towards the cost of the work. |
rebate | Money returned after purchase, usually a fixed amount per item. |
subsidy | A public contribution to the price, paid to the buyer or the installer. |
loan | A loan at market terms, often with a longer term or easier access. Not free money — is_cash is false. |
subsidised_loan | A loan below market rate, sometimes with part of it forgiven. |
tax_credit | A reduction in tax owed, one for one. |
tax_deduction | A reduction in taxable income; worth the deduction times the marginal tax rate. |
tax_exemption | Tax that is not charged at all — e.g. reduced or zero VAT or sales tax on the work. |
tax_reduction | A lower rate or partial relief on an ongoing tax, such as property tax. |
insurance_credit | A premium discount an insurer is required or chooses to give for the measure. |
tariff | Payment for energy the building exports, e.g. a feed-in or export tariff. |
performance_payment | Paid on measured results — energy saved or generated — rather than on cost. |
reimbursement | Costs repaid after the work, against receipts. |
fee_reduction | A lower utility or public charge — e.g. a stormwater fee reduced for a green roof. Not a tax. |
discount | A lower purchase price rather than money received — e.g. a council-run bulk-buy auction. |
other | Anything the above do not fit; the incentive's own type_label says what it is. |
Incentive class
Each incentive's incentive_class: what KIND of thing it is. A true incentive is created by policy; a firm's own pricing and a plain fact are not awards. market programmes are never listed by the estimators (their value is already inside insurance_saving), and a context row is never counted.
| Value | Description |
|---|---|
policy | Created by law or a regulated programme: a tax credit, grant, rebate, exemption or a premium discount the state requires insurers to give. |
financing | Money lent (PACE and similar). Nothing is taken off the cost; it changes when you pay, not how much. |
market | A private firm's own pricing — e.g. an insurer's risk-improvement credits. Belongs in payback, not in a list of incentives. |
context | A fact, not an action — e.g. "no state sales tax" or a community's NFIP Community Rating System class. |
Upgrade
The upgrade parameter, each incentive's upgrades, and the estimators' upgrades. Not every code is priced in every country — GET /v1/upgrades lists the ones your key can see.
| Value | Description |
|---|---|
aero | Aerothermal heat pump (A/C + heat). Energy efficiency — no hazard it reduces. |
air | Compressed air / extraction efficiency. Resilience: heatwave. |
asset_raising | Raising services and equipment above flood level (electrics, heating, HVAC, tanks, machinery). Resilience (flood) — appears on incentives; not priced by the estimators. |
attic | Attic insulation (to 500mm). Energy efficiency — no hazard it reduces. |
battery | Battery storage (commercial only since 21 Sep 2026). Resilience: power_outage. |
bms | Building management system. Resilience: heatwave. |
cool_roof | Cool roof coating / reflective membrane. Resilience: heatwave. |
defensible | Defensible space + vegetation management. Resilience: wildfire. |
doors | Wind-rated roller shutter doors. Resilience: hurricane, storm. |
drainage | Stormwater drainage system. Resilience: flood, skybrud, landslide. |
dry_floodproofing | Dry floodproofing (sealed envelope + opening shields). Resilience (flood) — appears on incentives; not priced by the estimators. |
elevation | Elevating the building above flood level. Resilience: flood. |
emberproof | Ember-resistant assemblies (vents, eaves, Class A roof). Resilience: wildfire. |
emberseal | Gutter Guards + Garage Door Seals. Resilience: wildfire. |
evap_cooling | Evaporative cooling system. Resilience: heatwave. |
facade | Facade insulation (external). Energy efficiency — no hazard it reduces. |
fire | Fire suppression upgrade (restaurant/kitchen). Resilience: fire. |
fireroof | Class A Fire-Resistant Roof. Resilience: wildfire. |
floating_foundation | Stilts, piers or a floating foundation. Resilience (flood) — appears on incentives; not priced by the estimators. |
flood | Perimeter flood barrier system. Resilience: flood, skybrud. |
flood_barrier | Flood barriers / stop-logs (batardeaux). Resilience: flood. |
flood_door | Flood-resistant doors. Resilience: flood. |
flood_vents | Engineered flood vents. Resilience: flood. |
garage | Impact Garage Door. Resilience: hurricane, storm. |
generator | Standby generator (100 kW). Resilience: power_outage. |
glazing | High-performance commercial glazing. Energy efficiency — no hazard it reduces. |
gshp | Ground-source heat pump. Resilience: heatwave. |
hailroof | Hail-resistant roof covering (IK10 rated). Resilience: storm, hail. |
heatpump | Heat pump, replacing gas. Resilience: heatwave. |
hpwh | Heat Pump Water Heater. Energy efficiency — no hazard it reduces. |
hvac | High-efficiency HVAC (SCOP rated). Energy efficiency — no hazard it reduces. |
hvac_upgrade | Enhanced commercial HVAC / cooling. Resilience: heatwave, coldwave. |
insulation | Rooftop insulation upgrade. Resilience: coldwave. |
led | LED + smart lighting. Energy efficiency — no hazard it reduces. |
loft | Loft insulation (300mm). Energy efficiency — no hazard it reduces. |
night_purge | Night-purge ventilation. Resilience: heatwave. |
nonreturn_valve | Non-return valves + automatic air bricks. Resilience: flood. |
refrig_upgrade | High-efficiency refrigeration upgrade. Resilience: heatwave. |
roof | Storm-rated commercial roof. Resilience: hurricane, storm, tornado. |
roofins | Roof insulation (Rc ≥ 6.0). Energy efficiency — no hazard it reduces. |
roofstruct | Structural roof reinforcement (snow load). Energy efficiency — no hazard it reduces. |
roofwall | Roof-to-Wall Clips / Straps. Resilience: hurricane, storm. |
sacrificial_ground_floor | Sacrificial ground floor — a lower level designed to be flooded and re-fitted. Resilience (flood) — appears on incentives; not priced by the estimators. |
seismic | Seismic reinforcement. Resilience: earthquake. |
seismic_bracebolt | Foundation Bolting + Cripple-Wall Bracing. Resilience: earthquake. |
seismic_chimney | Masonry Chimney Removal (metal-flue rebuild). Resilience: earthquake. |
seismic_waterheater | Water-Heater Seismic Strapping. Resilience: earthquake. |
shutters | Impact-rated rolldown shutters. Resilience: hurricane, storm. |
smart_multizone | Smart home energy system (multi-zone). Energy efficiency — no hazard it reduces. |
smart_thermostat | Smart thermostat (single zone). Energy efficiency — no hazard it reduces. |
snow | Structural roof reinforcement (snow load). Resilience: snow_load. |
solar | Commercial rooftop solar (50 kW). Energy efficiency — no hazard it reduces. |
solarthermal | Solar thermal water heating. Energy efficiency — no hazard it reduces. |
sprinkler | Sprinkler upgrade (ESFR / EN 12845). Resilience: fire. |
sump_pump | Sump pump with check valve. Resilience: flood. |
valves | Thermostatic radiator valves. Energy efficiency — no hazard it reduces. |
ventilation | Balanced ventilation w/ heat recovery. Energy efficiency — no hazard it reduces. |
vents | Ember-Resistant Vents. Resilience: wildfire. |
wall | Solid wall insulation (external). Energy efficiency — no hazard it reduces. |
wallins | Interior wall insulation (ITI). Energy efficiency — no hazard it reduces. |
windows | Impact Windows. Resilience: hurricane, storm. |
green_roof | Green roof. Resilience (cloudburst, heat) — appears on incentives; not priced by the estimators. |
rainwater_harvesting | Rainwater harvesting. Resilience (cloudburst) — appears on incentives; not priced by the estimators. |
unsealing | Unsealing / de-paving (permeable surfaces). Resilience (cloudburst) — appears on incentives; not priced by the estimators. |
tree_planting | Tree planting. Resilience (heat) — appears on incentives; not priced by the estimators. |
Incentive mode
Each incentive's mode.
| Value | Description |
|---|---|
residential | Homes only. |
commercial | Businesses, public bodies and non-residential buildings only. |
both | Being retired. A programme for homes and non-residential buildings alike is becoming two records — residential and commercial — sharing one reference number (FR22r, FR22c). |
Programme status
Each incentive's active_2026.
| Value | Description |
|---|---|
YES | Live: the programme is running. |
CHECK | Uncertain — suspended, under review or between rounds. Confirm with the grantor before relying on it. |
CONDITIONAL | Opens only when a condition is met — for example after a government-designated flood event, or while a scheme window is open. The conditions and eligibility summary say which. |
LIKELY | Believed to be running, but not confirmed from the grantor's own page. Confirm with the grantor before relying on it. |
N/A | No yearly status applies — typically a row recording that a state offers no such programme. Treat like CHECK. |
(null) | Not yet recorded. Treat like CHECK. |
NO | Ended. Never returned by the list or read endpoints; listed for completeness. |
Funding availability
Each incentive's availability.state. counts_toward_roi is false for every state but open.
| Value | Description |
|---|---|
open | Funded and taking applications. Counts toward any total. |
waitlist | Funding paused, but the grantor is still taking applications — apply now to join the queue. Shown with $0; never counted. |
hiatus | The budget is exhausted; typically refunded annually — apply after the refunding date. Shown with $0; never counted. |
prioritised_other | Funds are currently reserved for a different group of applicants. Shown with 0; never counted. |
closed | Not taking applications. Still returned so the award is not lost if it reopens; shown with 0; never counted. Only a person sets this: an automated status is never stronger than waitlist. |
Applicant
Each incentive's applicant.
| Value | Description |
|---|---|
owner | The building's owner or occupier applies directly. |
(text) | Anything else names who applies instead — a community, a utility, a public body — for a programme the owner cannot claim (claimable_by_owner false). |
Grantor type
Each grantor's type.
| Value | Description |
|---|---|
federal_national | National government or one of its agencies. |
state_province | A US state, German Land, French région or equivalent. |
city_county | A city, county or other local authority. |
utility | An energy or water utility. |
insurer | An insurer or insurance pool. |
lender | A bank or lender, typically offering a subsidised loan. |
nonprofit | A charity or non-profit programme operator. |
other | Any other body. |
VAT basis
A cost rule's vat_basis.
| Value | Description |
|---|---|
net | The figure excludes VAT / sales tax; it is added according to the country's rates. |
gross | The figure already includes VAT / sales tax. |
unknown | The source does not say. |
Cost basis
How a cost figure was derived (cost_basis, with the costs.provenance grant).
| Value | Description |
|---|---|
native | Priced from a source in this country. |
indexed | Another country's native price × the Eurostat construction price-level ratio × exchange rate. |
fx_only | Another country's price converted at the exchange rate only (no price-level index exists for the pair). |
eu | An EU-wide figure. |
unsourced | No source yet — treat as an estimate. |
Hazard level
Each hazard's level in GET /v1/risk/address.
| Value | Description |
|---|---|
red | High or extreme for this address. |
orange | Moderate. |
green | Low. |
grey | No rating: the source has insufficient data, or the hazard does not apply. |
Hazard not answered
A hazard's why when it carries no level.
| Value | Description |
|---|---|
absent | Never modelled for this country — not a finding of low risk. |
unavailable | Modelled, but the source could not answer this time. Retry later. |
Time unit
A recovery curve's time_unit.
| Value | Description |
|---|---|
days | Closure and recovery measured in days (most hazards). |
hours | Measured in hours (short interruptions such as power outages). |
Payback classification
An estimate's payback.classification.
| Value | Description |
|---|---|
investment | Pays back within the measures' service life. |
beyond-life | Pays back, but only after the measures would need replacing. |
none | The benefits never repay the net cost. |
compliance | Required by law or code; bought regardless of payback. |
Who bears the loss
The bearer of each money line in POST /v1/estimate/supplychain. Different bearers are never summed.
| Value | Description |
|---|---|
owner | The building's owner. |
insurer | Paid by the owner's insurer. |
counterparty | Falls on a customer or supplier downstream. |
uncovered | Nobody's policy pays it: the owner's own loss. |
Job status
A portfolio job's status.
| Value | Description |
|---|---|
queued | Accepted, waiting for a worker. |
running | Being priced. |
done | Finished; results attached. |
failed | Could not be completed; the error is attached. |
expired | Results were kept 7 days and have been removed. |
Coverage view
The view parameter on GET /v1/coverage/aggregate.
| Value | Description |
|---|---|
us | United States, by state and county. |
eu | The European countries, by region. |
Usage range
The range parameter on GET /v1/usage — how far back the series reaches.
| Value | Description |
|---|---|
today | Since midnight in your timezone. |
3d | Last 3 days. |
1w | Last week. |
2w | Last 2 weeks. |
1m | Last month (the default). |
3m | Last 3 months. |
6m | Last 6 months. |
1y | Last year. |
all | Since the key was issued. |
Hazard
Hazard identifiers — the risk parameter and hazard keys in responses.
| Value | Description |
|---|---|
earthquake | Ground shaking. |
fire | Fire starting inside the building. |
flood | River, coastal or surface-water flooding. |
hail | Hailstones — roof covering and glazing damage. |
heatwave | Prolonged extreme heat — comfort, operations and cooling load. |
hurricane | Tropical cyclone wind. |
power_outage | Loss of grid electricity. |
skybrud | Cloudburst — intense short rainfall overwhelming drainage (Danish/Nordic usage). |
snow_load | Weight of snow on the roof. |
storm | Severe convective or extratropical windstorm. |
wildfire | Wildland or vegetation fire reaching the building. |
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. |
key_archived | 403 | The key has been archived — the arrangement it belonged to has ended. Its usage history is retained. |
scope_denied | 403 | Your key does not grant this endpoint, country, mode or site. 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. |