How often named phrases are searched, and what a click costs

Measures phrases the caller already has. It answers, for each phrase named, how many people search it in a month, what an advertising click on it costs,…

POST /v1/seo/keywords

SEO → · All API references → · Six flows, four surfaces →


Address	`https://api.hanzo.ai/v1/seo/keywords`
Method	`POST`
Operation	`seoKeyword`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Measures phrases the caller already has.

It answers, for each phrase named, how many people search it in a month, what an advertising click on it costs, and how contested that advertising is. This is the ground fact of search: everything else on this surface is a question about phrases, and this is the one that says whether a phrase is worth having.

Give it phrases you already suspect. To find phrases you have not thought of, use seoIdea; to find the ones a site already places for, use seoRank.

The market defaults to the United States in English. It is priced per request rather than per phrase, so asking about fifty phrases costs what asking about one does.

Request

3 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.
`location`	body	integer	—	Location is the market, as the upstream's numeric code.

Response

Status	Body	Meaning
`200`	seoKeywordOut	ok

200 body — 8 fields.

Field	In	Type	Always	Description
`cost`	body	string	—	Cost is what this call cost, in USD, as an exact decimal string.
`keywords`	body	seoMetric[]	—	Keywords is one measurement per phrase, in the order the upstream answered.
`keywords[].competition`	body	number	—	Competition is how contested the advertising is, from 0 to 1.
`keywords[].cpc`	body	number	—	CPC is the average cost of one advertising click, in USD.
`keywords[].difficulty`	body	integer	—	Difficulty is how hard the first page is to reach organically, 0 to 100.
`keywords[].keyword`	body	string	—	Keyword is the phrase.
`keywords[].level`	body	string	—	Level is the same fact as a word: low, medium or high.
`keywords[].volume`	body	integer	—	Volume is the average monthly searches.

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.seoKeyword({ 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_keyword(keywords=["<keywords>"], language="<language>")

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.SeoAPI.SeoKeyword(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_keyword(&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).seoKeyword();

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/keywords \
  -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.

SEO API · All Hanzo APIs · Interactive reference

How often named phrases are searched, and what a click costs

Request

Response

Examples

On this page