docs / endpoint

POST /v1/keywords/volume

Historical Google keyword search volume and competition metrics.

Credits: 20 credits per call. Timeout: 60s

Parameters

NameTypeRequiredDefaultDescription
keywords array required — Keywords to fetch search volume 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.
search_partners boolean optional false Include Google Search Network partner sites in the volume figures. Optional, default false.
tag string optional — Optional label for your own bookkeeping; not echoed back in the response.

Request

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

{
  "keywords": [
    "running shoes",
    "trail running shoes"
  ],
  "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_rpiva3tl5joh3bvfqxrxqfr5",
  "request_id": "req_7gmesd2cijjfbe6outlsx7472m",
  "object": "keyword_volume",
  "created_at": "2026-07-29T12:00:00Z",
  "elapsed_ms": 244,
  "credits": {
    "charged": 20,
    "balance": 9857
  },
  "data": {
    "location": {
      "code": 2840,
      "name": "United States"
    },
    "language": {
      "code": "en",
      "name": "English"
    },
    "network": "google_search",
    "items_count": 2,
    "items": [
      {
        "keyword": "running shoes",
        "avg_monthly_searches": 90500,
        "competition": "HIGH",
        "competition_index": 88,
        "cpc": 1.24,
        "low_bid": 0.42,
        "high_bid": 2.1,
        "monthly": [
          {
            "month": "2026-06",
            "search_volume": 91000
          },
          "…"
        ]
      },
      {
        "keyword": "trail running shoes",
        "avg_monthly_searches": 8100,
        "competition": "MEDIUM",
        "competition_index": 54,
        "cpc": 0.87,
        "low_bid": 0.31,
        "high_bid": 1.55,
        "monthly": [
          {
            "month": "2026-06",
            "search_volume": 8300
          },
          "…"
        ]
      }
    ]
  }
}

Response fields

What each field in data (above) means.

FieldDescription
data.location Resolved geotarget for this call.
data.location.code Google Ads geotarget ID.
data.location.name Human-readable geotarget name.
data.language Resolved language for this call.
data.language.code ISO language code.
data.language.name Human-readable language name.
data.network Search network the volume figures are drawn from, e.g. "google_search".
data.items_count Number of entries in items.
data.items One row per requested keyword.
data.items[].keyword The keyword.
data.items[].avg_monthly_searches Average monthly search volume over the trailing 12 months.
data.items[].competition Advertiser competition level: LOW, MEDIUM, or HIGH.
data.items[].competition_index 0-100 advertiser competition score (finer-grained than competition).
data.items[].cpc Average cost-per-click for advertisers bidding on this keyword.
data.items[].low_bid Low end of the typical top-of-page bid range.
data.items[].high_bid High end of the typical top-of-page bid range.
data.items[].monthly Month-by-month search volume history.
data.items[].monthly[].month Month this row covers, YYYY-MM.
data.items[].monthly[].search_volume Search volume for that month.