# Create competitors

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

> Names the domains that place for the same phrases.

`POST /v1/seo/competitors`

> [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/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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo seo competitors
```

**SDK**

**.ts**

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

**.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_competitor(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.SeoCompetitor(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_competitor(&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).seoCompetitor();
```

**HTTP**

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

**MCP**

Tool `seo`, op `seoCompetitor` — 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": "seoCompetitor",
           "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)