Reference

Resolve a location

resolve_location: Turns free text such as 20 miles of Leeds, Yorkshire or LS1 into region, county, town, postcode or radius filters, each with a count and a ready filter.

Generated from the contractsView as Markdown

Turns free text such as 20 miles of Leeds, Yorkshire or LS1 into region, county, town, postcode or radius filters, each with a count and a ready filter. Ambiguous places come back as candidates with a question, so ask the user which they meant rather than choosing. Free and needs no account, though a radius under 5 miles needs an account. Add the chosen filter to the audience, then call count_audience. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

Property	Value
Tool name	`resolve_location`
Position in tools/list	6 of 22
Cost	Free
Scope	None. Works without an account.
Annotations	readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Kind	Read only; idempotent, not destructive, closed world
REST equivalent	`POST /v1/locations/resolve`

Input

The schema sets additionalProperties to false, so a member that is not listed is refused.

Member	Type	Required	Description
`text`	string	yes	Free text such as "20 miles of Leeds", "Yorkshire" or "SW1".
`radius_miles`	number (1 to 100)	no
`dataset`	enum: `uk_contacts`, `ie_contacts`, `global_contacts`	no	The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served.

Example call

The params of a tools/call request:

{
  "name": "resolve_location",
  "arguments": {
    "text": "20 miles of Leeds"
  }
}

Output

The result carries structuredContent that matches this schema, and one line of text that leads with the number.

Member	Type	Always present	Description
`text`	string	yes
`ambiguous`	boolean	yes	True when more than one candidate fits; ask the person which they meant.
`question`	string or null	yes
`candidates`	array of `LocationCandidate`	yes
`candidates[].kind`	enum: `region`, `county`, `town`, `local_authority`, `postcode_area`, `postcode_district`, `postcode_sector`, `postcode_unit`, and 2 more	yes
`candidates[].code`	string	yes	The filter code, or the ONS code for a centre.
`candidates[].label`	string	yes
`candidates[].contacts`	integer (0 or more) or `under 10` or `suppressed`	yes	A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5.
`candidates[].centre`	object or null	yes
`candidates[].filter`	`Filter`	yes	A ready filter for this candidate.
`disclosure`	`Disclosure`	yes	Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers.
`disclosure.level`	enum: `exact`, `rounded`	yes	exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5.
`disclosure.rounded_to`	integer or null	yes	5 when numbers are rounded; null when they are exact.
`disclosure.secondary_suppression`	boolean	yes	True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced.
`disclosure.notes`	array of string	yes

Errors

A failed call returns isError true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with code, detail, next_step and did_you_mean. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See Errors.