docs / endpoint

POST /v1/keywords/difficulty

Keyword difficulty (0-100) per keyword; unscored keywords return pending and are scored for a later call.

Credits: 110 credits per call. Timeout: 120s

Parameters

NameTypeRequiredDefaultDescription
keywords array required — Keywords to score difficulty for. Required, non-empty. Array of string. Max 500 items.
location any optional 2840 Google Ads geotarget ID, an ISO country code (e.g. "US"), or a country name. Optional, default 2840 (United States). For anything narrower than a country, look up its ID with /v1/locations.
language string required — ISO language code. Required.
tag string optional — Optional label for your own bookkeeping; not echoed back in the response.

Request

→ requestPOST /v1/keywords/difficulty
POST /v1/keywords/difficulty HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "keywords": [
    "buy running shoes",
    "cold keyword"
  ],
  "location": 2840,
  "language": "en"
}

Response

The usual envelope (id, request_id, object, created_at, elapsed_ms, credits) is documented once on The Contract. Below is an example response with this endpoint's data. Values vary per request; … marks an array cut short.

← response200
{
  "id": "keyw_y4zlhnwzb5oofgqslo64leja",
  "request_id": "req_wtumkpqpubojpcq43dh5hehjja",
  "object": "keyword_difficulty",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 244,
  "credits": {
    "charged": 110,
    "balance": 9857
  },
  "data": {
    "items_count": 2,
    "items": [
      {
        "keyword": "buy running shoes",
        "difficulty": 42,
        "status": "available"
      },
      {
        "keyword": "cold keyword",
        "difficulty": null,
        "status": "pending"
      }
    ]
  }
}

Response fields

What each field in data (above) means.

FieldDescription
data.items_count Number of entries in items.
data.items One row per requested keyword.
data.items[].keyword The keyword.
data.items[].difficulty 0-100 difficulty score, or null while status is "pending".
data.items[].status "available" once scored, or "pending" if the keyword is not scored yet. Retry the same keyword later to resolve it.