Address autocomplete
GET /v1/address/autocompleteRanked candidates for a partial address or postcode, free; the entry point that narrows a search before the one priced resolve.
Same call over MCP
Autocomplete a UK addressaddress_autocompleteAuthenticate 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/address/autocomplete returns
The free entry point. Type part of an address or a postcode and get ranked candidates back; pick one and hand it to address_resolve for the canonical record and the UPRN. Resolve, lookup and the postcode listing are priced because they return Ordnance Survey AddressBase content; narrowing a search is not, so this is the call to make on every keystroke and the resolve is the call to make once at the end.
The full description, as the assistant reads it
This is the free entry point: resolve, lookup and postcode listing are priced because they return OS AddressBase content, but narrowing a search is not. Prefer it for anything interactive, and resolve once at the end.
UK only.
Reference
When to use it, and when not to
Use it for anything interactive: a search box, an assistant asking "which of these did you mean", a script that has a messy address and wants to see the candidates before committing. max_results bounds the list. When you already know the exact address, skip to address_resolve; when you want every address at a postcode, address_by_postcode returns them all for 10 credits.
Inputs
Before you call it
q is the partial address or postcode as typed. country defaults to the UK and is the only value the platform serves today.
Request
Calling GET /v1/address/autocomplete
curl "https://api.marketcode.ai/v1/address/autocomplete?q=Lordship%20Lane%20SE22&max_results=3" \
-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 |
|---|---|---|---|---|
| q | Query | string | Yes | Partial address or postcode |
| country | Query | string | No | One of: UKDefault: UK |
| max_results | Query | integer | No | Default: 10 |
Response
What GET /v1/address/autocomplete returns for a real request
curl "https://api.marketcode.ai/v1/address/autocomplete?q=Lordship%20Lane%20SE22&max_results=3" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"query": "Lordship Lane SE22",
"country": "UK",
"data": {
"data": {
"candidates": [
{
"uprn": "200003441110",
"address": "83 LORDSHIP LANE, LONDON, SE22 8EP",
"postcode": "SE22 8EP",
"property_type": null,
"match_score": 0.621,
"session": null
},
{
"uprn": "200003441439",
"address": "422 LORDSHIP LANE, LONDON, SE22 8NE",
"postcode": "SE22 8NE",
"property_type": null,
"match_score": 0.621,
"session": null
},
{
"uprn": "200003443636",
"address": "87A LORDSHIP LANE, LONDON, SE22 8EP",
"postcode": "SE22 8EP",
"property_type": null,
"match_score": 0.6,
"session": null
}
],
"auto_select": false,
"query": "Lordship Lane SE22"
}
},
"credits_charged": 0
}A real response, captured from production and trimmed: arrays to three items, long strings shortened, volatile keys dropped.
Response
Response fields
| Field | Type | Example |
|---|---|---|
| query | string | Lordship Lane SE22 |
| country | string | UK |
| data | object | |
| data.data | object | |
| data.data.candidates | array | |
| data.data.candidates[].uprn | string | 200003441110 |
| data.data.candidates[].address | string | 83 LORDSHIP LANE, LONDON, SE22 8EP |
| data.data.candidates[].postcode | string | SE22 8EP |
| data.data.candidates[].property_type | null | |
| data.data.candidates[].match_score | number | 0.621 |
| data.data.candidates[].session | null | |
| data.data.auto_select | boolean | false |
| data.data.query | string | Lordship Lane SE22 |
| credits_charged | integer | 0 |
Fields observed in the example response above; a field the example did not exercise is not listed.
Reference
Things that catch people out
- Candidates are not records. A candidate is enough to choose from; the licensed record with the UPRN comes from the resolve. Do not treat a candidate string as an identifier.
- Flats and subdivided houses need the unit. "12 Lordship Lane" is a building; "Flat 2, 12 Lordship Lane" is a home. Narrow to the unit before resolving, or the resolve returns the building.
- Great Britain. AddressBase covers England, Scotland and Wales. Northern Ireland is not in it.
Price and licence
What it costs, and where the data comes from
Address autocomplete 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
AddressBase
Used under licence from Ordnance Survey · Great Britain
Related
Endpoints used with Address autocomplete
- Resolve an address to a UPRN8 credits
address_resolveResolve free-text address to canonical record (UPRN for UK).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
FAQ
Questions about Address autocomplete
How much does `address_autocomplete` cost?
+
Address autocomplete 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.
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_autocomplete 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).
Does `address_autocomplete` 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 is this free when the resolve costs 8 credits?
+
Because the two return different things. This returns candidate strings so you can narrow; the resolve returns the licensed AddressBase record for one address with its UPRN. The licence is what is paid for.
How many results should I ask for?
+
Three to five for a person choosing from a list; one when a script is confident and wants the top match to pass straight to the resolve.
Does an assistant need to be told to do this?
+
No. The MarketCode skills tell it to autocomplete first, resolve once and carry the UPRN through the conversation. Without the skills, the tool descriptions say the same thing and a capable assistant follows them.
Try Address autocomplete on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.