Skip to main content

Location and language lookup endpoints; readable 422s; ISO country codes accepted

Two new reference-data endpoints let you look up the location and language values that POST /v1/domains/{domain_uuid}/keywords accepts, keyword create now takes an ISO country code for country-wide tracking, and its 422 responses name the failing field and how to fix it.

New: GET /v1/locations and GET /v1/languages​

  • GET /v1/locations lists the location catalogue for one search engine (search_engine=google|bing|yahoo, default google). Filter by country (ISO 3166-1 alpha-2), variant (Country, City, Postal Code, …), code (an exact geo-target id) or q (a prefix of the City,Region,Country name, 2–100 characters). With none of country, code or q it lists the countries. Each row's code is the value to send as search_engines[].location.
  • GET /v1/languages lists the language codes for one engine; q matches the exact code or a substring of the name. The Global language 0000 is never listed because keyword create rejects it.
  • Both are paginated with page / per_page (default 100, max 1000) and the X-Total-Count, X-Total-Pages, X-Per-Page and X-Current-Page headers, require an API key with API access like every other /v1 endpoint, and are not account-scoped.

See Reference values for the full parameter tables and worked examples.

Changed: keyword create​

  • search_engines[].location accepts an ISO 3166-1 alpha-2 country code ("FR") as well as the geo-target id ("2250"). The ISO form resolves to the engine's country row, so both create the same keyword and it reads back with location.code 2250.
  • name, device and language are matched case-insensitively and trimmed (Google, Desktop, FR are accepted and normalised to google, desktop, fr). frequency was already case-insensitive.
  • 422 responses are structured. An unknown frequency, name, device, location or language returns code invalid_reference_value with a source.pointer to the exact field and a meta block (field, value, search_engine, allowed, lookup, docs). Every failure comes back in one response, except that an entry whose name is unknown has its location and language checked only once the engine is fixed. A body with the wrong shape (missing frequency, words that is not an array of strings or is empty, search_engines not an array of objects) returns code validation_failed with the same source.pointer / meta.field envelope. Previously the detail was the raw database lookup message (Couldn't find Location …). See Errors & rate limits.
  • 404 bodies are uniform across /v1: code not_found with a detail such as Domain not found, instead of the raw lookup message.

The API Reference has been regenerated from the API's own request specs and now includes both lookup endpoints under Reference data.