Address resolve
POST /v1/address/resolveTurn a free-text UK address into its canonical record and UPRN, the identifier every other per-property tool takes.
Same call over MCP
Resolve an address to a UPRNaddress_resolveAuthenticate 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/address/resolve returns
Almost every MarketCode workflow starts here. A person has an address as text: "Flat 2, 12 Lordship Lane, London SE22 8HN", or half of that with a typo. The property record, the valuation, the sale history, the energy certificates and the ownership all hang off a Unique Property Reference Number, and this call is how the text becomes that number.
The match runs against Ordnance Survey AddressBase, the national address register, and returns the canonical record as the register holds it with its UPRN, ranked when more than one candidate fits. It costs 8 credits because the response carries a licensed AddressBase record.
Reference
When to use it, and when not to
Use it once per address, at the end of an interactive search, when you already know which address you mean. For narrowing a partial address as the user types, use address_autocomplete, which is free and returns ranked candidates without the licensed record; resolve the chosen candidate afterwards. For "every address at this postcode" use address_by_postcode. If you already hold a UPRN and want the address back, address_by_uprn is the reverse lookup.
An assistant with the MarketCode skills installed does this without being asked: the skills tell it to autocomplete first, resolve once, then carry the UPRN through the rest of the conversation.
Request
Calling POST /v1/address/resolve
curl -X POST "https://api.marketcode.ai/v1/address/resolve" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"query":"12 Lordship Lane, London SE22 8HN","max_results":1}'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 |
|---|---|---|---|---|
| query | Body | string | Yes | |
| country | Body | string | No | One of: UKDefault: UK |
| max_results | Body | integer | No | Default: 5 |
Response
What POST /v1/address/resolve returns for a real request
curl -X POST "https://api.marketcode.ai/v1/address/resolve" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"query":"12 Lordship Lane, London SE22 8HN","max_results":1}'{
"data": {
"data": {
"id": "<string>",
"uprn": 0,
"similarity_distance": null,
"match_score": 0,
"distance": null,
"address": "<string>",
"address_highlight": null,
"confidence_score": 0,
"exact_match": false,
"is_residential": false,
"last_verified": "<string>",
"source": "<string>",
"session": null,
"elements": {
"building_number": "<string>",
"building_name": null,
"sub_building_name": null,
"thoroughfare": "<string>",
"locality": null,
"town": "<string>",
"postcode": "<string>",
"country": "<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 |
|---|---|
| data | object |
| data.data | object |
| data.data.id | string |
| data.data.uprn | integer |
| data.data.similarity_distance | null |
| data.data.match_score | integer |
| data.data.distance | null |
| data.data.address | string |
| data.data.address_highlight | null |
| data.data.confidence_score | integer |
| data.data.exact_match | boolean |
| data.data.is_residential | boolean |
| data.data.last_verified | string |
| data.data.source | string |
| data.data.session | null |
| data.data.elements | object |
| data.data.elements.building_number | string |
| data.data.elements.building_name | null |
| data.data.elements.sub_building_name | null |
| data.data.elements.thoroughfare | string |
| data.data.elements.locality | null |
| data.data.elements.town | string |
| data.data.elements.postcode | string |
| data.data.elements.country | string |
| credits_charged | integer |
Fields observed in the example response above; a field the example did not exercise is not listed.
Reference
Things that catch people out
- Flats in subdivided houses. Some upstream datasets record the building rather than the unit. The resolve returns the unit's UPRN where AddressBase has one; a later tool (auction history, some listings) may still match at building level and say so.
- Scotland resolves, England-and-Wales data follows. AddressBase covers Great Britain, but the sold-price record is HM Land Registry's and covers England and Wales. A Scottish UPRN is real; its sale history here is empty.
- Set
max_resultsto 1 for a clean pipeline. The default returns several ranked candidates so an assistant can disambiguate; a script that already knows the address wants one. - Failed calls are not charged. A query that matches nothing returns an empty candidate list and costs nothing.
Price and licence
What it costs, and where the data comes from
Address resolve costs 8 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
AddressBase
Used under licence from Ordnance Survey · Great Britain
Related
Endpoints used with Address resolve
- Autocomplete a UK addressFree
address_autocompleteFree address autocomplete. Returns ranked candidates for a partial addressPairs with this - Property summary4 credits
property_summaryOne-call summary of a property: what it is, what building it belongs to,Pairs with this - List the addresses at a postcode10 credits
address_by_postcodeReturn all addresses at a UK postcode.Pairs with this - Look up an address by UPRN8 credits
address_by_uprnLook up an address by UPRN (UK only).Pairs with this - Full valuation with back-seriesFree
valuation_fullFull valuation block for a property: the value and its range, a monthlySame product - Comparable properties6 credits
property_compsComparable properties in the same building or block, with missingSame product
Glossary
Terms used here
- UPRN: The Unique Property Reference Number: a 12-digit identifier every addressable location in Great Britain carries, and the key MarketCode joins property records on.
- Model Context Protocol (MCP): An open protocol that lets an AI assistant discover and call tools on a remote server; MarketCode exposes every data operation as an MCP tool that Claude, ChatGPT, Codex and Cursor can call.
- Credit (MarketCode): The unit MarketCode meters calls in: most tools are free, licensed and model-run tools cost a fixed number per successful call, and one balance covers MCP, REST and the products.
FAQ
Questions about Address resolve
How much does `address_resolve` cost?
+
Address resolve costs 8 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.
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 address_resolve 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 AddressBase. Coverage is Great Britain (Ordnance Survey AddressBase).
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 `address_resolve` 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.
Why does address resolution cost credits when autocomplete is free?
+
Because the two return different things. Autocomplete returns ranked candidate strings so you can narrow a search; resolve returns the licensed AddressBase record for one address, with its UPRN. The licence is what is paid for, so the free call is the one to loop over and the priced call is the one to make once.
Can I resolve a postcode on its own?
+
A bare postcode resolves to candidates at that postcode; for the full list use address_by_postcode, which returns every address there in one call for 10 credits.
What is in the response?
+
The canonical AddressBase record for each candidate with its UPRN, plus the credits charged and your remaining balance. The example on this page shows the shape once a capture exists; because the record is licensed, the example shows the keys with placeholder values.
Try Address resolve on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.