# Keyword Rank Visibility API
Check a domain’s organic search visibility for a target keyword.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/v1/websitetools/search-visibility
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/v1/websitetools/search-visibility/demo
- **Live Demo:** https://gugudata.io/demo/search-visibility
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/search-visibility/llm
- **Raw Markdown:** https://gugudata.io/details/search-visibility/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Keyword and domain visibility check: Submit one keyword and target domain to observe whether the domain appears within the selected rank depth.
- Observed SERP item data: Return result items, best rank, top-ranked URL, rank depth, and visibility metrics for reporting workflows.
- Competitor comparison fields: Add competitor domains to compare target visibility against other domains in the same observed result set.
- Locale and source controls: Use request parameters to align checks with the market, source, and rank depth needed by your SEO workflow.
- Credit usage transparency: The response reports request credit cost and remaining credits so scheduled checks can be monitored.
- Dashboard and report integration: Use the structured JSON response in SEO dashboards, weekly reports, client reporting, and growth monitoring jobs.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| query | string | true | search visibility api | Keyword or search phrase to observe. |
| domain | string | true | gugudata.com | Target domain to match in organic results. |
| source | string | false | google_web | Search source. Supported values: google_web, baidu_web. bing_web can be enabled separately. |
| maxRank | integer | false | 20 | Maximum organic rank depth to observe. Supported values: 10, 20, 50. |
| locale | string | false | en | Language preference for the observation. |
| region | string | false | United States | Search region preference. |
| competitors | array<string> | false | | Optional competitor domains to compare, up to 10 domains. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| dataStatus | object | Response status information. |
| data | object | Search visibility observation result. |
| data.query | string | Observed keyword. |
| data.domain | string | Target domain. |
| data.source | string | Search source used for the observation. |
| data.maxRank | integer | Observed rank depth. |
| data.checkedAt | string | Observation timestamp. |
| data.creditCost | integer | Credits consumed by this request. |
| data.remainingCredits | integer | Remaining credits for the current plan when available. |
| data.metrics | object | Visibility metrics including best rank, top 10, top 20, and score. |
| data.observedItems | array<object> | Observed organic result items. |
| data.brandMatches | array<object> | Organic result matches for the target domain. |
| data.competitorMatches | array<object> | Organic result matches for competitor domains. |
| data.searchMetadata | object | Observation metadata. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 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 request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 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. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/v1/websitetools/search-visibility?appkey=YOUR_APPKEY' --request POST --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'query=search visibility api' --data-urlencode 'domain=gugudata.com' --data-urlencode 'source=google_web' --data-urlencode 'maxRank=20' --data-urlencode 'locale=en' --data-urlencode 'region=United States' --data-urlencode 'competitors=YOUR_VALUE'
```