# 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.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/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. 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`](https://emailmovers.com/mydatahub/docs/reference/rest/resolve-location.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## 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:

```json
{
  "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](https://emailmovers.com/mydatahub/docs/errors.md).