Building stock profile
GET /v1/buildings/stock-profile/{area_id}Composition of the built stock in an area: unit counts, HMO share, mixed-use share, median building height and footprint, solar penetration.
Same call over MCP
Built-stock profile of an areaarea_stock_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/buildings/stock-profile/{area_id} returns
Medians, not means — one tower would skew an average height enough to make a low-rise district read as mid-rise. Percentages are whole percentages.
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 GET /v1/buildings/stock-profile/{area_id}
curl "https://api.marketcode.ai/v1/buildings/stock-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/buildings/stock-profile/{area_id} returns for a real request
curl "https://api.marketcode.ai/v1/buildings/stock-profile/c0694b59-04d1-48ab-9a4c-c4f9d7b74f60" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"error": "HTTP 502",
"detail": "The origin web server returned an invalid or incomplete response to Cloudflare. This typically indicates the origin is overloaded or misconfigured."
}The call failed with these arguments; the status and message are shown rather than an invented body.
Price and licence
What it costs, and where the data comes from
Building stock 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
- Ordnance Survey
National Geographic Database (buildings, land and sites)
Used under licence from Ordnance Survey · Great Britain
Related
Endpoints used with Building stock profile
- Resolve an area nameFree
area_resolveResolve an area name or code ("Hackney", "E5") to its area_id, centroidNamed in the description - Physical form of buildings3 credits
building_physicalPhysical form of the buildings a set of UPRNs sit in: height, volume, footprint area, floor count, construction and roof material, basement, green roof, solar panels, and the residential/commercial unit mix.Same category - Hex-binned density for mapsFree
h3_densityHex-binned stock and transaction density for map layers, at H3 resolution 8.Same category - Mixed-use buildings in an area6 credits
mixed_use_buildingsBuildings holding BOTH residential and commercial units — the conversion and permitted-development cohort.Same category - Plot utilisation of land parcels6 credits
plot_utilisationLand parcels by size and how much of them is built on. Set `max_built_coverage` to 0.2 to find largely undeveloped plots.Same category
Glossary
Terms used here
- Mixed-use building: A building that holds both residential and commercial units; a property of the building's unit mix rather than of any single unit, and the conversion cohort.
- House in multiple occupation (HMO): A property let to three or more tenants from more than one household who share facilities; licensed by the council above five occupants and often restricted by Article 4.
FAQ
Questions about Building stock profile
How much does `area_stock_profile` cost?
+
Building stock 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. area_stock_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 area_stock_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 Ordnance Survey NGD. Coverage is the UK.
Does `area_stock_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 Building stock profile on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.