Land plot utilisation
POST /v1/land/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 call over MCP
Plot utilisation of land parcelsplot_utilisationAuthenticate 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/land/plot-utilisation returns
Parcels with NO measured coverage are excluded when you set a ceiling, rather than counted as empty — unknown coverage is not evidence of a vacant plot. Coverage is measured on about 41% of parcels.
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/land/plot-utilisation
curl -X POST "https://api.marketcode.ai/v1/land/plot-utilisation" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","max_built_coverage":0.2,"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 |
| min_area_m2 | Body | number | No | Default: 0 |
| max_built_coverage | Body | number | No | Built footprint as a share of plot; 0.2 finds largely undeveloped parcels. Parcels with no MEASURED coverage are excluded when this is set, rather than counted as empty. |
| limit | Body | integer | No | Default: 100 |
Response
What POST /v1/land/plot-utilisation returns for a real request
curl -X POST "https://api.marketcode.ai/v1/land/plot-utilisation" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"area_id":"c0694b59-04d1-48ab-9a4c-c4f9d7b74f60","max_built_coverage":0.2,"limit":3}'{
"area_id": "<string>",
"min_area_m2": 0,
"max_built_coverage": 0,
"parcels": [
{
"land_id": "<string>",
"area_m2": "<string>",
"built_coverage_ratio": "<string>",
"landuse_tier_a": "<string>",
"landuse_tier_b": "<string>",
"nlud_code": "<string>",
"n_buildings": 0,
"n_units_via_buildings": 0,
"total_buildings_footprint_m2": "<string>",
"address_count_residential": 0,
"address_count_commercial": 0
}
],
"count": 0,
"coverage_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 |
|---|---|
| area_id | string |
| min_area_m2 | integer |
| max_built_coverage | number |
| parcels | array |
| parcels[].land_id | string |
| parcels[].area_m2 | string |
| parcels[].built_coverage_ratio | string |
| parcels[].landuse_tier_a | string |
| parcels[].landuse_tier_b | string |
| parcels[].nlud_code | string |
| parcels[].n_buildings | integer |
| parcels[].n_units_via_buildings | integer |
| parcels[].total_buildings_footprint_m2 | string |
| parcels[].address_count_residential | integer |
| parcels[].address_count_commercial | integer |
| count | integer |
| coverage_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
Land plot utilisation 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 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 Land plot utilisation
- 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 - 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
FAQ
Questions about Land plot utilisation
How much does `plot_utilisation` cost?
+
Land plot utilisation 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 Ordnance Survey. 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. plot_utilisation 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 plot_utilisation 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 `plot_utilisation` 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 Land plot utilisation on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.