# Keyword research + domain overview

Keyword ideas with volume, CPC, competition and difficulty; any domain's ranked keywords, traffic, top pages, competitors and keyword gaps.

## Research: plans and credits used

`GET /research` · scope `research:read`

For keyword research and domain overview: whether it is on the account, the plan, credits a month and credits used this month.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/research" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/research", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/research", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "keyword_research": {
      "active": true,
      "plan": "Pro",
      "credits": {
        "used": 12,
        "limit": 350
      }
    },
    "domain_overview": {
      "active": false,
      "plan": null,
      "credits": {
        "used": 0,
        "limit": 0
      }
    }
  }
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## Countries and languages covered

`GET /research/markets` · scope `research:read`

The countries (location_code) and languages (language_code) keyword research and domain overview answer for. Free.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/research/markets" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/research/markets", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/research/markets", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": [
    {
      "location_code": 2840,
      "name": "United States",
      "languages": [
        [
          "en",
          "English"
        ]
      ]
    }
  ]
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## Research a keyword

`POST /keyword-research` · scope `research:run`

Up to 100 keywords, by search volume. Uses 1 credit - or none if this account asked the same question in the last 30 days.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `keyword` | body | string | yes | The seed keyword (up to 80 characters). |
| `kind` | body | string (one of: matching, related, questions, ideas) | no | matching = longer terms containing the keyword; related = what people also search; questions = question searches; ideas = broader ideas from the same topic. Default: `matching`. |
| `location_code` | body | integer | no | Country code from GET /research/markets (2840 = United States). Default: `2840`. |
| `language_code` | body | string | no | Language code from GET /research/markets (default: the country's main language). |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/keyword-research" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/keyword-research", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/keyword-research", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "keyword": "dog grooming",
    "kind": "matching",
    "credits_used": 1,
    "seed": {
      "keyword": "dog grooming near me",
      "search_volume": 74000,
      "cpc_usd": 2.1,
      "competition": 0.41,
      "difficulty": 23,
      "intent": "transactional",
      "trend_12m": [
        60500,
        74000
      ]
    },
    "total_in_database": 5310,
    "keywords": [
      {
        "keyword": "dog grooming near me",
        "search_volume": 74000,
        "cpc_usd": 2.1,
        "competition": 0.41,
        "difficulty": 23,
        "intent": "transactional",
        "trend_12m": [
          60500,
          74000
        ]
      }
    ]
  }
}
```

Errors: `payment_required`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Search volume in a region or city

`POST /keyword-research/local-volumes` · scope `research:run`

Monthly searches for each keyword in that area. Uses 4 credits (or none if asked before).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `keywords` | body | array | yes | Up to 1,000 keywords. |
| `location_code` | body | integer | yes | Any Google location: a country, region or city (the rank-tracking location list). |
| `language_code` | body | string | no | Language code. Default: `en`. |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/keyword-research/local-volumes" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/keyword-research/local-volumes", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/keyword-research/local-volumes", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "location": "Manchester,England,United Kingdom",
    "credits_used": 4,
    "volumes": {
      "dog grooming": 1900
    }
  }
}
```

Errors: `payment_required`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Domain overview report

`POST /domain-overview` · scope `research:run`

Ranked keywords (top 100 by traffic), estimated monthly traffic, position spread, top pages and competitors. Uses 1 credit - or none if this account asked in the last 14 days.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | body | string | yes | Any domain, like example.com. |
| `location_code` | body | integer | no | Country code from GET /research/markets (2840 = United States). Default: `2840`. |
| `language_code` | body | string | no | Language code from GET /research/markets (default: the country's main language). |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/domain-overview" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/domain-overview", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/domain-overview", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "domain": "example.com",
    "credits_used": 1,
    "metrics": {
      "keywords": 1520,
      "traffic": 8400.5,
      "traffic_value": 12650.0,
      "positions": [
        3,
        10,
        40,
        80,
        90,
        100,
        110,
        120,
        130,
        140,
        150,
        160
      ]
    },
    "keywords": [
      {
        "keyword": "dog grooming near me",
        "search_volume": 74000,
        "cpc_usd": 2.1,
        "competition": 0.41,
        "difficulty": 23,
        "intent": "transactional",
        "trend_12m": [
          60500,
          74000
        ],
        "position": 4,
        "url": "https://example.com/page/",
        "traffic": 310.2
      }
    ],
    "pages": [
      {
        "url": "https://example.com/",
        "keywords": 120,
        "traffic": 900.1
      }
    ],
    "competitors": [
      {
        "domain": "competitor.com",
        "shared_keywords": 240,
        "average_position": 18.5
      }
    ]
  }
}
```

Errors: `payment_required`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Keyword gap vs competitors

`POST /domain-overview/gap` · scope `research:run`

Keywords the competitors rank for and your domain does not, most-shared first. One credit per competitor not asked in the last 14 days.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | body | string | yes | Your domain. |
| `competitors` | body | array | yes | 1 to 3 competitor domains. |
| `location_code` | body | integer | no | Country code from GET /research/markets (2840 = United States). Default: `2840`. |
| `language_code` | body | string | no | Language code from GET /research/markets (default: the country's main language). |

### Example

```bash
curl -s -X POST "https://app.pbn.ltd/api/v1/domain-overview/gap" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.post("https://app.pbn.ltd/api/v1/domain-overview/gap", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/domain-overview/gap", {
  method: "POST",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "domain": "example.com",
    "competitors": [
      "a.com",
      "b.com"
    ],
    "credits_used": 2,
    "keywords": [
      {
        "keyword": "dog grooming near me",
        "search_volume": 74000,
        "cpc_usd": 2.1,
        "competition": 0.41,
        "difficulty": 23,
        "intent": "transactional",
        "trend_12m": [
          60500,
          74000
        ],
        "competitor_positions": {
          "a.com": 3,
          "b.com": 8
        }
      }
    ]
  }
}
```

Errors: `payment_required`, `rate_limited`, `scope_missing`, `unauthorized`, `validation_failed`

## Saved keyword lists

`GET /keyword-research/lists` · scope `research:read`

Your saved keyword lists.

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/keyword-research/lists" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/keyword-research/lists", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/keyword-research/lists", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": [
    {
      "id": 7,
      "name": "Blog ideas",
      "site_id": 12345,
      "keywords": 42
    }
  ]
}
```

Errors: `rate_limited`, `scope_missing`, `unauthorized`

## One keyword list

`GET /keyword-research/lists/{list_id}` · scope `research:read`

The keywords in one of your lists, with their saved metrics.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `list_id` | path | integer | yes | The list id. |

### Example

```bash
curl -s "https://app.pbn.ltd/api/v1/keyword-research/lists/list_id" \
  -H "Authorization: Bearer $PBN_API_KEY"
```

```python
import os
import requests

headers = {"Authorization": "Bearer " + os.environ["PBN_API_KEY"]}
r = requests.get("https://app.pbn.ltd/api/v1/keyword-research/lists/list_id", headers=headers, timeout=120)
print(r.status_code, r.json())
```

```javascript
const res = await fetch("https://app.pbn.ltd/api/v1/keyword-research/lists/list_id", {
  method: "GET",
  headers: {Authorization: `Bearer ${process.env.PBN_API_KEY}`}
});
console.log(res.status, await res.json());
```

### Response

`200`

```json
{
  "data": {
    "id": 7,
    "name": "Blog ideas",
    "keywords": [
      {
        "keyword": "dog grooming near me",
        "search_volume": 74000,
        "cpc_usd": 2.1,
        "competition": 0.41,
        "difficulty": 23,
        "intent": "transactional",
        "trend_12m": [
          60500,
          74000
        ]
      }
    ]
  }
}
```

Errors: `not_found`, `rate_limited`, `scope_missing`, `unauthorized`