Energy profile
GET /v1/energy/profile/{area_id}Energy composition of an area: EPC band mix, mains gas / electric / oil split, heat-pump penetration.
Same call over MCP
Energy profile of an areaenergy_profileAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What GET /v1/energy/profile/{area_id} returns
area_id is the marts area id from area_resolve — pass analytics_area_id, not area_id, if the resolve response gives both.
Percentages are of properties HOLDING an EPC, not of all stock, and are whole percentages (0-100). EPCs are lodged on sale or let, so long-held and social housing are under-represented — say so when reporting a figure.
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 GET /v1/energy/profile/{area_id}
curl "https://api.marketcode.ai/v1/energy/profile/c0694b59-04d1-48ab-9a4c-c4f9d7b74f60" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| area_id | Path | string | Yes | Marts area id from /areas/resolve |
Response
What GET /v1/energy/profile/{area_id} returns for a real request
curl "https://api.marketcode.ai/v1/energy/profile/c0694b59-04d1-48ab-9a4c-c4f9d7b74f60" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"area_id": "c0694b59-04d1-48ab-9a4c-c4f9d7b74f60",
"n_certificates": 104941,
"band_mix": [
{
"band": "A",
"n": 109
},
{
"band": "B",
"n": 14168
},
{
"band": "C",
"n": 43657
},
"… 4 more"
],
"pct_a_b": 13.6,
"pct_d_or_worse": 44.8,
"pct_mains_gas": 81.7,
"pct_electric": 11.4,
"pct_oil": 0,
"pct_heat_pump": 0.4,
"units": "percent (0-100), of certificated stock only",
"coverage_note": "Percentages are of properties holding an EPC, not of all stock. EPCs are lodged on sale or let, so long-held and social housing are under-represented.",
"credits_charged": 0
}A real response, captured from production and trimmed: arrays to three items, long strings shortened, volatile keys dropped.
Response
Response fields
| Field | Type | Example |
|---|---|---|
| area_id | string | c0694b59-04d1-48ab-9a4c-c4f9d7b74f60 |
| n_certificates | integer | 104941 |
| band_mix | array | |
| band_mix[].band | string | A |
| band_mix[].n | integer | 109 |
| pct_a_b | number | 13.6 |
| pct_d_or_worse | number | 44.8 |
| pct_mains_gas | number | 81.7 |
| pct_electric | number | 11.4 |
| pct_oil | integer | 0 |
| pct_heat_pump | number | 0.4 |
| units | string | percent (0-100), of certificated stock only |
| coverage_note | string | Percentages are of properties holding an EPC, no |
| credits_charged | integer | 0 |
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 profile is free over MCP and over REST, and the two surfaces share one credit balance. Free calls need a signed-in account or an API key and appear in your usage, but they never touch your balance.
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 profile
- Resolve an area nameFree
area_resolveResolve an area name or code ("Hackney", "E5") to its area_id, centroidNamed in the description - 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 - Retrofit candidates in an area6 credits
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 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.
- 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 profile
How much does `energy_profile` cost?
+
Energy profile is free over MCP and over REST, and the two surfaces share one credit balance. Free calls need a signed-in account or an API key and appear in your usage, but they never touch your balance.
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. energy_profile 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 energy_profile 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.
Does `energy_profile` 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 profile on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.