Building physical
POST /v1/buildings/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 call over MCP
Physical form of buildingsbuilding_physicalAuthenticate 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/buildings/physical returns
year_built and num_floors are thinly populated and come back null rather than estimated — treat null as unknown, not as absent.
UK only.
Inputs
Before you call it
- uprns
- A UPRN is the Unique Property Reference Number every UK address carries. Narrow the address with address_autocomplete, which is free, then address_resolve returns the UPRN for 8 credits. property_summary and address_by_postcode return UPRNs too.
Request
Calling POST /v1/buildings/physical
curl -X POST "https://api.marketcode.ai/v1/buildings/physical" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"uprns":["200003443835"]}'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 |
|---|---|---|---|---|
| uprns | Body | integer[] | Yes |
Response
What POST /v1/buildings/physical returns for a real request
curl -X POST "https://api.marketcode.ai/v1/buildings/physical" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"uprns":["200003443835"]}'{
"buildings": [
{
"building_id": "<string>",
"uprn": 0,
"height_m_above_sea_level": 0,
"building_height_m": "<string>",
"volume_m3": 0,
"total_footprint_area_m2": "<string>",
"num_floors": 0,
"construction_material": "<string>",
"roof_material": "<string>",
"roof_shape": "<string>",
"basement_presence": "<string>",
"green_roof_presence": "<string>",
"solar_panel_presence": "<string>",
"building_use_primary": "<string>",
"year_built": null,
"n_units": 0,
"n_residential_units": 0,
"n_commercial_units": 0,
"n_hmo_units": 0
}
],
"count": 0,
"coverage_note": "<string>",
"match_note": "<string>",
"height_note": "<string>",
"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 |
|---|---|
| buildings | array |
| buildings[].building_id | string |
| buildings[].uprn | integer |
| buildings[].height_m_above_sea_level | number |
| buildings[].building_height_m | string |
| buildings[].volume_m3 | number |
| buildings[].total_footprint_area_m2 | string |
| buildings[].num_floors | integer |
| buildings[].construction_material | string |
| buildings[].roof_material | string |
| buildings[].roof_shape | string |
| buildings[].basement_presence | string |
| buildings[].green_roof_presence | string |
| buildings[].solar_panel_presence | string |
| buildings[].building_use_primary | string |
| buildings[].year_built | null |
| buildings[].n_units | integer |
| buildings[].n_residential_units | integer |
| buildings[].n_commercial_units | integer |
| buildings[].n_hmo_units | integer |
| count | integer |
| coverage_note | string |
| match_note | string |
| height_note | string |
| 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
Building physical costs 3 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 Ordnance Survey. A call that fails is not charged.
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 physical
- Built-stock profile of an areaFree
area_stock_profileComposition of the built stock in an area: unit counts, HMO share, mixed-use share, median building height and footprint, solar penetration.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
- Floor area: The internal area of a property in square metres, taken from its energy certificate or measured from building geometry; the input the valuation model cannot do without.
- 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.
FAQ
Questions about Building physical
How much does `building_physical` cost?
+
Building physical costs 3 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 Ordnance Survey. A call that fails is not charged.
Do I need to resolve the address first?
+
Yes. building_physical takes a UPRN, not an address. Start with address_autocomplete (free) to narrow the address, then address_resolve (8 credits) to get the UPRN. An assistant with the MarketCode skills installed does both steps on its own.
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 building_physical 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.
Can I store or republish the results?
+
The response includes records we license from Ordnance Survey. 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 `building_physical` 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 physical on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.