Create competitors

Names the domains that place for the same phrases.

POST /v1/seo/competitors

SEO → · All API references → · Get started →

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 (int64)	—	Limit is how many domains to return, 1 to 1000.
`location`	body	integer (int64)	—	Location is the market, as the upstream's numeric code.

Response

Status	Body	Meaning
`200`	seo.seoCompetitorOut	ok
`default`	problem-details	refused

200 body — 8 fields.

Field	In	Type	Always	Description
`competitors`	body	seo.seoDomain[]	—	Competitors is one row per domain, strongest first.
`competitors[].domain`	body	string	—	Domain is the competitor.
`competitors[].keywords`	body	integer (int64)	—	Keywords is how many of the phrases it places for.
`competitors[].position`	body	number (double)	—	Position is its average rank across the phrases.
`competitors[].traffic`	body	number (double)	—	Traffic is the estimated monthly visits those placements earn.
`competitors[].visibility`	body	number (double)	—	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 (int64)	—	Total is how many domains the upstream holds for these phrases.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo seo competitors

.ts

.py

.go

.rs

.java

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 := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.SeoAPI.SeoCompetitor(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::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.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new SeoApi(client).seoCompetitor();

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>"
     }'

Tool seo, op seoCompetitor — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "seo",
         "arguments": {
           "op": "seoCompetitor",
           "input": {
             "keywords": [
               "<keywords>"
             ],
             "language": "<language>"
           }
         }
       }
     }'

SEO API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate backlinks NextCreate ideas