# Create keywords

URL: https://docs.hanzo.ai/docs/openapi/seo/seokeyword

> Measures phrases the caller already has.

`POST /v1/seo/keywords`

> [SEO →](https://docs.hanzo.ai/docs/openapi/seo) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                        |
| ------------- | -------------------------------------- |
| **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 (int64) | —        | Location is the market, as the upstream's numeric code. |

## Response

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

`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 | seo.seoMetric\[] | —      | Keywords is one measurement per phrase, in the order the upstream answered. |
| `keywords[].competition` | body | number (double)  | —      | Competition is how contested the advertising is, from 0 to 1.               |
| `keywords[].cpc`         | body | number (double)  | —      | CPC is the average cost of one advertising click, in USD.                   |
| `keywords[].difficulty`  | body | integer (int64)  | —      | 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 (int64)  | —      | Volume is the average monthly searches.                                     |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo seo keywords
```

**SDK**

**.ts**

```ts
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>" });
```

**.py**

```python
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>")
```

**.go**

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

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

**.rs**

```rust
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_keyword(&cfg, Default::default()).await?;
```

**.java**

```java
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).seoKeyword();
```

**HTTP**

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

**MCP**

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

```bash
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": "seoKeyword",
           "input": {
             "keywords": [
               "<keywords>"
             ],
             "language": "<language>"
           }
         }
       }
     }'
```

---

[SEO API](https://docs.hanzo.ai/docs/openapi/seo) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)