Every phrase a domain already places for, with its position
Reports every phrase a domain already places for.
POST /v1/seo/rankings
| Address | https://api.hanzo.ai/v1/seo/rankings |
| Method | POST |
| Operation | seoRank |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Reports every phrase a domain already places for.
For each one it gives the phrase, the position on the results page, the page of the site that placed, that result's headline, the phrase's monthly searches and the visits the placement is estimated to earn. It is the single most direct question about a site's search visibility — yours or a competitor's, since it takes any domain.
Position is the ABSOLUTE rank, counting every element on the page — the ads, the answer boxes, the map — because that is what a person scrolling actually passes. An organic-only rank flatters a result that sits below half a screen of other things.
It is priced per row, so Limit decides what the call costs, and Total says how many more there were.
Request
4 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
domain | body | string | — | Domain is the site, with or without a subdomain — "hanzo.ai", "docs.hanzo.ai". |
language | body | string | — | Language is the ISO code. |
limit | body | integer | — | Limit is how many placements to return, 1 to 1000. |
location | body | integer | — | Location is the market, as the upstream's numeric code. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | seoRankOut | ok |
200 body — 9 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
cost | body | string | — | Cost is what this call cost, in USD, as an exact decimal string. |
rankings | body | seoRanking[] | — | Rankings is one row per phrase the domain places for. |
rankings[].keyword | body | string | — | Keyword is the phrase searched. |
rankings[].position | body | integer | — | Position is the absolute rank on the results page, counting every element — so it is what a person scrolling actually passes, not the organic-only rank. |
rankings[].title | body | string | — | Title is that result's headline. |
rankings[].traffic | body | number | — | Traffic is the estimated monthly visits this placement earns. |
rankings[].url | body | string | — | URL is the page of the target that placed. |
rankings[].volume | body | integer | — | Volume is the phrase's average monthly searches. |
total | body | integer | — | Total is how many placements the upstream holds for this domain. |
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.seoRank({ domain: "<domain>", 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_rank(domain="<domain>", language="<language>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.SeoAPI.SeoRank(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_rank(&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).seoRank();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/rankings \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "<domain>",
"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?