Reference

Resolve a location

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

Generated from the contractsView as Markdown

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`
Tag	Catalogue

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

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

{
  "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.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	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`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	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.