# Resolve a location

> POST /v1/locations/resolve. Turn free text into region, county, town, postcode or radius filters.

Source: https://emailmovers.com/mydatahub/docs/reference/rest/resolve-location

`POST /v1/locations/resolve`

Turn free text into region, county, town, postcode or radius filters. Ambiguous names come back as candidates with a question, never a silent choice. A radius under 5 miles needs an account (401 account-required).

| Property | Value |
| --- | --- |
| Endpoint | `POST https://mydatahub.emailmovers.com/v1/locations/resolve` |
| Operation id | `resolveLocation` |
| Cost | Free (0 credits) |
| Access | No account needed. An API key or OAuth token with the scope `counts:read` is optional and adds your organisation's own figures. |
| MCP tool | [`resolve_location`](https://emailmovers.com/mydatahub/docs/reference/mcp/resolve_location.md) |
| Tag | Catalogue |

> **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 page describes the contract the API is tested against.

## Request

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `MyDataHub-Version` | header | string | no | The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window. |

### Body

| 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 request

```bash
curl -X POST "https://mydatahub.emailmovers.com/v1/locations/resolve" \
  -H "Content-Type: application/json" \
  --data '{
  "text": "20 miles of Leeds"
}'
```

## Responses

### 200: Candidates for the place.

Headers: `RateLimit`, `RateLimit-Policy`.

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

#### Example response

```json
{
  "text": "20 miles of Leeds",
  "ambiguous": true,
  "question": "Leeds: city centre or the metropolitan district?",
  "candidates": [
    {
      "kind": "radius",
      "code": "E08000035",
      "label": "Within 20 miles of Leeds (metropolitan district centroid)",
      "contacts": 42318,
      "centre": {
        "lat": 53.7997,
        "lon": -1.5492
      },
      "filter": {
        "field": "site.location",
        "op": "within_radius",
        "centre": {
          "place": "Leeds",
          "code": "E08000035"
        },
        "radius_miles": 20
      }
    },
    {
      "kind": "radius",
      "code": "LS1",
      "label": "Within 20 miles of Leeds city centre (LS1)",
      "contacts": 41960,
      "centre": {
        "lat": 53.7974,
        "lon": -1.5438
      },
      "filter": {
        "field": "site.location",
        "op": "within_radius",
        "centre": {
          "postcode": "LS1"
        },
        "radius_miles": 20
      }
    }
  ],
  "disclosure": {
    "level": "rounded",
    "rounded_to": 5,
    "secondary_suppression": false,
    "notes": [
      "Counts under 100 and every breakdown cell are rounded to the nearest 5 for anonymous and trial callers."
    ]
  }
}
```

## Errors

Every error is a problem object with a `code` and a `next_step`. Every response carries the `RateLimit` and `RateLimit-Policy` headers; see [Rate limits](https://emailmovers.com/mydatahub/docs/rate-limits.md).

| Status | Problem codes | When |
| --- | --- | --- |
| 400 | [`invalid-request`](https://emailmovers.com/mydatahub/docs/errors/invalid-request.md), [`idempotency-key-required`](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required.md), [`unsupported-version`](https://emailmovers.com/mydatahub/docs/errors/unsupported-version.md) | The request could not be read, or an Idempotency-Key is missing. |
| 401 | [`authentication-required`](https://emailmovers.com/mydatahub/docs/errors/authentication-required.md), [`account-required`](https://emailmovers.com/mydatahub/docs/errors/account-required.md) | Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required). |
| 422 | [`validation-failed`](https://emailmovers.com/mydatahub/docs/errors/validation-failed.md), [`quote-required`](https://emailmovers.com/mydatahub/docs/errors/quote-required.md), [`dataset-unavailable`](https://emailmovers.com/mydatahub/docs/errors/dataset-unavailable.md) | The request is not valid. errors lists every problem with a JSON pointer and did_you_mean. |
| 429 | [`rate-limited`](https://emailmovers.com/mydatahub/docs/errors/rate-limited.md) | Too many requests. Wait for Retry-After. |
| Any other failure | [`internal-error`](https://emailmovers.com/mydatahub/docs/errors/internal-error.md), [`service-unavailable`](https://emailmovers.com/mydatahub/docs/errors/service-unavailable.md), [`tps-screen-expired`](https://emailmovers.com/mydatahub/docs/errors/tps-screen-expired.md) | Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old. |