Energy retrofit candidates
POST /v1/energy/retrofit-candidatesProperties in an area with the most improvement headroom, ranked by potential efficiency. Defaults to the sub-standard bands E, F and G.
Same call over MCP
Retrofit candidates in an arearetrofit_candidatesAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What POST /v1/energy/retrofit-candidates returns
A targeting tool: it returns a list to act on, not a fact about one property. Combine with fuel='gas' for the fossil-heated cohort that carries the largest retrofit case.
area_id is the marts area id from area_resolve.
UK only.
Inputs
Before you call it
- area_id
- The area id is the analytics area identifier, not a name or a GSS code. Call area_resolve with a place name or code ("Hackney", "E5") first; it is free and returns the id with the area's hierarchy. Where it gives both
area_idandanalytics_area_id, passanalytics_area_id.
Request
Calling POST /v1/energy/retrofit-candidates
curl -X POST "https://api.marketcode.ai/v1/energy/retrofit-candidates" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","limit":3}'Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
This endpoint takes no path or query parameters.
Request body
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| area_id | Body | string | Yes | Marts area id from /areas/resolve |
| bands | Body | string[] | No | EPC bands to include. One or more of ['A', 'B', 'C', 'D', 'E', 'F', 'G']. |
| fuel | Body | string | No | Substring match on main heating fuel, e.g. 'gas'. |
| limit | Body | integer | No | Default: 100 |
Response
What POST /v1/energy/retrofit-candidates returns for a real request
curl -X POST "https://api.marketcode.ai/v1/energy/retrofit-candidates" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","limit":3}'{
"area_id": "<string>",
"bands": [
"<string>"
],
"fuel": null,
"candidates": [
{
"uprn": 0,
"current_rating": "<string>",
"potential_efficiency": 0,
"main_fuel": "<string>",
"heating_system": "<string>",
"total_floor_area": "<string>",
"property_type": "<string>",
"built_form": "<string>",
"tenure": "<string>",
"construction_age_band": "<string>",
"inspection_date": "<string>",
"address_phrase": "<string>",
"asset_subtype": null,
"retrofit_gap": {
"points": 0,
"from_band": "<string>",
"from_score_estimated": 0,
"to_score": 0,
"basis": "<string>"
}
}
],
"count": 0,
"credits_charged": 0
}Shape only. This call returns licensed records, so the keys are real and every value is a placeholder of its type.
Response
Response fields
| Field | Type |
|---|---|
| area_id | string |
| bands | array |
| fuel | null |
| candidates | array |
| candidates[].uprn | integer |
| candidates[].current_rating | string |
| candidates[].potential_efficiency | integer |
| candidates[].main_fuel | string |
| candidates[].heating_system | string |
| candidates[].total_floor_area | string |
| candidates[].property_type | string |
| candidates[].built_form | string |
| candidates[].tenure | string |
| candidates[].construction_age_band | string |
| candidates[].inspection_date | string |
| candidates[].address_phrase | string |
| candidates[].asset_subtype | null |
| candidates[].retrofit_gap | object |
| candidates[].retrofit_gap.points | integer |
| candidates[].retrofit_gap.from_band | string |
| candidates[].retrofit_gap.from_score_estimated | integer |
| candidates[].retrofit_gap.to_score | integer |
| candidates[].retrofit_gap.basis | string |
| count | integer |
| credits_charged | integer |
Fields observed in the example response above; a field the example did not exercise is not listed.
Price and licence
What it costs, and where the data comes from
Energy retrofit candidates costs 6 credits per successful call over MCP and over REST, and the two surfaces share one credit balance.
The price covers licensed records in the response, from Ministry of Housing, Communities and Local Government. A call that fails is not charged.
Credits are granted on sign-up and bought in packs; the pricing page lists every call.
Sources
- Ministry of Housing, Communities and Local Government
Energy Performance Certificates (domestic and non-domestic)
MHCLG's EPC open data terms · England and Wales
Related
Endpoints used with Energy retrofit candidates
- Resolve an area nameFree
area_resolveResolve an area name or code ("Hackney", "E5") to its area_id, centroidNamed in the description - Energy profile of an areaFree
energy_profileEnergy composition of an area: EPC band mix, mains gas / electric / oil split, heat-pump penetration.Same category - EPC certificates for a propertyFree
epc_certificatesEvery Energy Performance Certificate lodged against a property, newest first, with current and potential efficiency, CO2, heating fuel and system, floor area and construction age.Same category - Solar potential of roofs4 credits
solar_potentialRoof characteristics for solar screening: footprint area, roof shape and material, building height, and whether panels are already present.Same category
Glossary
Terms used here
- EPC rating: The A to G energy efficiency band on an Energy Performance Certificate, lodged when a property is built, sold or let; MarketCode returns the full history of certificates, not just the latest.
- Retrofit gap: The difference between a property's current EPC score and the potential score its certificate says the recommended work would reach.
- Minimum energy efficiency standard (MEES): The rule that privately rented property in England and Wales must reach at least EPC band E, so F and G stock cannot legally be let without a registered exemption.
FAQ
Questions about Energy retrofit candidates
How much does `retrofit_candidates` cost?
+
Energy retrofit candidates costs 6 credits per successful call over MCP and over REST, and the two surfaces share one credit balance. The price covers licensed records in the response, from Ministry of Housing, Communities and Local Government. A call that fails is not charged.
Where do I get the area id?
+
From area_resolve, which is free: give it a place name or postcode district and it returns the area id, centroid and hierarchy. retrofit_candidates then takes that id.
How do I authenticate?
+
Send your API key as a Bearer token in the Authorization header. Keys are created in the API & MCP Hub, shown once and revocable. Every response carries the credits charged and your remaining balance.
Is there an MCP version?
+
Yes. The retrofit_candidates tool on the MarketCode MCP server is the same call at the same price, signed in with OAuth rather than a key, so Claude, ChatGPT, Codex and Cursor can run it in a conversation.
Where does the data come from?
+
Read from Ministry of Housing, Communities and Local Government EPC register. Coverage is the UK.
Can I store or republish the results?
+
The response includes records we license from Ministry of Housing, Communities and Local Government. Use them in your own analysis, reports and products; bulk redistribution of the raw records or building a competing dataset from them is not covered. Ask us if you need a redistribution licence.
Does `retrofit_candidates` change anything?
+
No. The tool is annotated read-only on the server, so it never writes to your data or ours and an assistant can call it without a confirmation step.
Try Energy retrofit candidates on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.