Check organic search visibility

Find whether a domain appears within a selected depth of organic search results. Compare observed rankings with competitor domains and use the results to support content reviews. A check is a point-in-time sample, not a guarantee of what every visitor sees or a promise of future ranking improvements.

View API details or try the Demo.

Make a request

curl --request POST \
  'https://api.gugudata.io/v1/websitetools/search-visibility?appkey=YOUR_APPKEY' \
  --header 'Content-Type: application/json' \
  --data '{"query":"search visibility api","domain":"gugudata.io","source":"google_web","maxRank":20,"locale":"en","region":"United States","competitors":[]}'

Parameter	Meaning
query	Required search phrase, up to 1,000 Unicode characters after normalization
domain	Required domain or HTTP/HTTPS URL; matching includes its subdomains
source	google_web or baidu_web; bing_web is available only when enabled
maxRank	Search depth: 10, 20 or 50; default 20
locale	Optional language, up to 35 characters
region	Optional search location, up to 100 characters
competitors	Up to ten competitor domains

Results depend on the query, location, language, search source and time of the check. Internationalized domain names are normalized for matching. URL paths and query strings do not narrow domain matching to one page.

Read the result

The data object includes the normalized query, domain, source, maxRank and checkedAt, followed by:

• observedItems: observed organic results with rank, title, URL, domain and snippet.
• brandMatches and competitorMatches: best rank and match count for matching domains.
• metrics: visibility, best rank, top-10/top-20 presence, matched count and a depth-relative score.
• searchMetadata: sampling status, available result count, observed item count and check URL.
• creditCost and remainingCredits: usage for the check and available balance when applicable.

Always inspect searchMetadata.status. The existing response contract can return UPSTREAM_UNAVAILABLE with HTTP 200 and zero credit cost. That means the check could not be completed, not that the domain has no search visibility. Do not store this state as a zero-rank measurement. A completed check with no matching domain is a valid result within the requested search depth.

Credits and Demo

Depths 10, 20 and 50 use multipliers of 1, 2 and 5. Google uses a source weight of 1; Baidu uses 10. Check the returned credit fields rather than assuming every request has the same cost. Account limits and authentication still apply.

The Demo performs a fixed search and caches a successful sample for 15 minutes. The X-GuGuData-Demo-Mode and X-GuGuData-Generated-At headers identify cached or newly generated samples. Rankings are variable; the Demo does not promise that the example domain will appear.

Handle errors

Validate the request before retrying HTTP 400. Check access for 401/403 and wait before retrying 429. On service errors or an unavailable sampling status, keep the previous successful observation and record the failed check separately. Do not automatically repeat a paid check without considering its cost.