Resolve an address to a UPRN
address_resolveTurn a free-text UK address into its canonical record and UPRN, the identifier every other per-property tool takes.
Same call over REST
Address resolve/v1/address/resolveNot connected yet? Connect your assistant. Sign in with your MarketCode account; no API key needed.
Reference
What address_resolve answers
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.
Example
An example call to address_resolve
Use the MarketCode tool address_resolve with {"query":"12 Lordship Lane, London SE22 8HN","max_results":1} and show me the result.{
"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.
Inputs
Arguments address_resolve takes
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | |
| country | string | No | Default: UK |
| max_results | integer | No | Default: 5 |
Response
What comes back
| 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.
Usage
How to run address_resolve in your assistant
Ask your assistant in plain English, for example:
"Use the MarketCode tool address_resolve for <address or area>.
Show the result and the credits charged."
The arguments the assistant will send, for the example on this page:
{"query":"12 Lordship Lane, London SE22 8HN","max_results":1}The connect steps for Claude, ChatGPT, Codex, Cursor and Claude Code are on the MCP page.
Skills
Skills that use address_resolve
- Property research: A sourced answer to any UK property question: the right tool for the job, the credit cost stated first, the wording rules that keep an estimate an estimate.
- Valuation report: An indicative valuation for one address: the range, the comparables and adjustments, the index position, the EPC, flood and planning context, and the reasoning, with every figure cited to the tool it came from.
- Due diligence report: A property due diligence report: title and ownership, history, EPC and council tax, flood and designations, nearby activity, cross-source disagreements and the cross-reference findings that join them, with a traffic light.
- Deal analysis: A first-pass appraisal of a site or asset: plot utilisation, planning position, market evidence, value and a residual against the cost assumptions you supply.
- Planning check: Every designation and constraint at an address, recent applications nearby and the flood position, laid out the way a planner reads them.
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
Tools 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.
Which assistants can run `address_resolve`?
+
Any MCP client: Claude (claude.ai, Claude Desktop, Claude Code), ChatGPT in developer mode, Codex and Cursor, each documented on the MCP page. You sign in with your MarketCode account over OAuth; there is no key to paste, and the connection is read-only.
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 in your assistant.
30-minute call. We'll connect your assistant live on a real address.