The domains that place for the same phrases
Names the domains that place for the same phrases.
POST /v1/seo/competitors
| Address | https://api.hanzo.ai/v1/seo/competitors |
| Method | POST |
| Operation | seoCompetitor |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Names the domains that place for the same phrases.
Given a set of phrases it returns the sites that appear across them, with each one's average position, how many of the phrases it places for, its share of the available attention and the visits that earns. It answers "who am I actually up against here", which is a different question from "who do I think my competitors are" and frequently a different answer.
Pair it with seoRank: this says who is in the race, seoRank says where any one of them finishes. It is priced per row, so Limit decides the cost.
Request
4 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
keywords | body | string[] | — | Keywords are the phrases. |
language | body | string | — | Language is the ISO code. |
limit | body | integer | — | Limit is how many domains to return, 1 to 1000. |
location | body | integer | — | Location is the market, as the upstream's numeric code. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | seoCompetitorOut | ok |
200 body — 8 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
competitors | body | seoDomain[] | — | Competitors is one row per domain, strongest first. |
competitors[].domain | body | string | — | Domain is the competitor. |
competitors[].keywords | body | integer | — | Keywords is how many of the phrases it places for. |
competitors[].position | body | number | — | Position is its average rank across the phrases. |
competitors[].traffic | body | number | — | Traffic is the estimated monthly visits those placements earn. |
competitors[].visibility | body | number | — | Visibility is its share of the possible attention across those phrases. |
cost | body | string | — | Cost is what this call cost, in USD, as an exact decimal string. |
total | body | integer | — | Total is how many domains the upstream holds for these phrases. |
Failure carries the platform error shape — see Errors.
Examples
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, SeoApi } from 'hanzoai';
const api = new SeoApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.seoCompetitor({ keywords: ["<keywords>"], language: "<language>" });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SeoApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SeoApi(client).seo_competitor(keywords=["<keywords>"], language="<language>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.SeoAPI.SeoCompetitor(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, seo_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = seo_api::seo_competitor(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SeoApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new SeoApi(client).seoCompetitor();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl -X POST https://api.hanzo.ai/v1/seo/competitors \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"keywords": [
"<keywords>"
],
"language": "<language>"
}'The door declares no tool for seo — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.
How is this guide?