Search Visibility API

Search Visibility API
Observe sampled search visibility for one keyword and domain. The API returns organic rank visibility, observed result items, competitor comparison, and credit usage for the request.

Method: POST
Path: /v1/websitetools/search-visibility
Demo: https://api.gugudata.io/v1/websitetools/search-visibility/demo
OpenAPI: https://gugudata.io/assets/openapi/gugudata.openapi.3.1.json

Request Parameters:

• appkey (string, required): Application key used for request authentication.
• query (string, required): Keyword or search phrase to observe.
• domain (string, required): Target domain to match in organic search results.
• source (string, optional): Search source, such as google_web or baidu_web.
• maxRank (integer, optional): Maximum organic rank depth. Supported values are 10, 20, and 50.
• locale (string, optional): Language preference for the observation.
• region (string, optional): Search region preference.
• competitors (array, optional): Optional competitor domains to compare.

Response Fields:

• query (string, required): Keyword observed by the request.
• domain (string, required): Normalized target domain.
• creditCost (integer, required): Credits consumed by the completed request. Upstream unavailable responses return 0.
• remainingCredits (integer, optional): Remaining annual credits when available.
• metrics.visibilityScore (number, required): Visibility score for the target domain.
• observedItems (array, required): Observed organic search result items.
• brandMatches (array, required): Matches for the target domain.
• competitorMatches (array, required): Matches for competitor domains.
• searchMetadata.status (string, required): Collection status such as COLLECTED or UPSTREAM_UNAVAILABLE.

Pricing:
The annual plan includes 120,000 search visibility credits for scheduled checks. Each response reports the credit cost before you expand keyword coverage.

HTTP Status Codes:

• 200: Request processed successfully. Some endpoints expose a separate application-level status field in the response body, such as dataStatus.statusCode.
• 400: Invalid request parameters or request format. Check required fields, data types, and request body format.
• 401: Missing or unknown application key. Provide a valid appkey with the request.
• 403: The application key is recognized but access is not allowed. The key may be expired, inactive, or not permitted for the requested API.
• 429: Request rate or trial usage limit exceeded. Reduce concurrency or retry after the limit window resets.
• 500: Internal service error. Retry later or contact support if the error persists.
• 503: Upstream service unavailable. Retry later; the requested upstream dependency is temporarily unavailable.

Business Status Codes:

• No endpoint-specific business status codes are documented.

Key Features:

• Production-ready HTTPS API with stable request and response contracts.

Details:
https://gugudata.io/details/search-visibility