Skip to main content
Domains connects SEO research to the hostnames your team localizes. Link a domain, prove you control it, then explore keywords, SERPs, and rank tracking for each supported market. The Domains item appears in the organization sidebar when the workspace-domains feature flag is enabled for your workspace.
  1. Open Domains in the sidebar.
  2. Click Link domain and enter the hostname (for example example.com).
  3. Complete verification on the link-domain page. Hyperlocalise supports:
    • DNS TXT — add a TXT record at _hyperlocalise.{domain}
    • HTML file — upload a token file to the site root
    • Meta tag — add a <meta> tag to the homepage
  4. Click Verify when the record or file is live.
Verification is attached to the hostname, not to individual markets. The first organization to verify a hostname owns that claim globally; another org cannot verify the same hostname while it stays verified. You can browse the research catalog before verification finishes. Keyword expansion, saving, SERP lookups, and rank tracking require a verified domain. Pending claims can be cancelled from the domain list. Verified domains cannot be deleted through the API.

​
Research surfaces

Open a linked domain to switch the sidebar to domain-scoped navigation. Each surface is its own route under /org/{slug}/domains/{domainId}/…. The locale selector lives in the page header, not as a separate tab. Pick a market to filter metrics and research data. The selected market persists in the URL as ?locale={marketId} and stays when you move between surfaces. If a market has no saved data yet, the UI shows an explicit empty state instead of mixing in another locale’s metrics.

​
Supported markets

Live domains currently expose four fixed research markets: Every verified domain can use all four markets. Research rows are stored per market in Postgres (marketId, DataForSEO locationCode, and languageCode). Custom per-domain locale lists and link-dialog locale editing are planned but not persisted yet. Linking sends only the hostname today.

​
Keyword research workflow

On Keyword research:
  1. Choose a market in the locale selector.
  2. Enter a seed keyword and expand ideas. Hyperlocalise calls DataForSEO Labs through the internal go-svc service (default 50 ideas, up to 200).
  3. Open a SERP snapshot for any idea to inspect live organic results.
  4. Save keywords you want to track or revisit. Saved keywords persist per domain and market.
Saved keywords and rank snapshots survive reloads. Ephemeral expand and SERP preview state lives only until you navigate away.

​
Rank tracking

On Rank tracking:
  1. Select keywords to track for the current market (up to 20 keywords per refresh request).
  2. Run a refresh to fetch live positions for your verified hostname.
  3. Historical snapshots are stored for each tracked keyword.
Rank checks use DataForSEO live SERP data. Batch refreshes process keywords in groups of 20 per market.

​
Operator setup

Domains research is optional infrastructure. Segment validation in go-svc works without it.

​
Web app

The Next.js app proxies research to go-svc over GO_SVC_URL. It does not read DATAFORSEO_API_KEY directly. The browser never sees the research service token.

​
go-svc

Set these on the go_svc Vercel service (see apps/go-svc/README.md): Without DATAFORSEO_API_KEY, research mutations return provider_not_configured or dataforseo_not_configured. Research routes require both a signed-in WorkOS session cookie and the server-only X-Go-Svc-Research-Token header. Only the web app should call them.

​
API (organization scope)

Authenticated org routes live under /api/orgs/{organizationSlug}/linked-domains. All routes require the workspace-domains flag.

​
Linked domains

​
Research

Nested under /linked-domains/{id}/research: Common error codes: linked_domain_not_found, market_not_found, provider_not_configured, provider_unavailable, provider_rate_limited.

​
Troubleshooting

​
Next