Retrofit candidates in an area
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 REST
Energy retrofit candidates/v1/energy/retrofit-candidatesNot connected yet? Connect your assistant. Sign in with your MarketCode account; no API key needed.
Reference
What retrofit_candidates answers
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.
Example
An example call to retrofit_candidates
Use the MarketCode tool retrofit_candidates with {"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","limit":3} and show me the result.{
"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.
Inputs
Arguments retrofit_candidates takes
| Name | Type | Required | Description |
|---|---|---|---|
| area_id | string | Yes | |
| bands | string[] | No | |
| fuel | string | No | |
| limit | integer | No | Default: 100 |
Response
What comes back
| 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.
Usage
How to run retrofit_candidates in your assistant
Ask your assistant in plain English, for example:
"Use the MarketCode tool retrofit_candidates for <address or area>.
Show the result and the credits charged."
The arguments the assistant will send, for the example on this page:
{"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","limit":3}The connect steps for Claude, ChatGPT, Codex, Cursor and Claude Code are on the MCP page.
Price and licence
What it costs, and where the data comes from
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
Tools used with 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 retrofit_candidates
How much does `retrofit_candidates` cost?
+
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.
Which assistants can run `retrofit_candidates`?
+
Any MCP client: Claude (claude.ai, Claude Desktop, Claude Code), ChatGPT in developer mode, Codex and Cursor, each documented on the MCP page. You sign in with your MarketCode account over OAuth; there is no key to paste, and the connection is read-only.
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 retrofit_candidates in your assistant.
30-minute call. We'll connect your assistant live on a real address.