google
keywords
seo

Get Google keyword search volume by country

Returns Google monthly search volume, cost per click, competition, and a 12-month trend for up to 20 keywords in one country. Response is { location, location_name, language, items }: each item carries keyword, search_volume (average monthly searches), cpc with its currency, competition (0 to 1) with competition_level, monthly_searches (the last 12 months, oldest first, as { year, month, search_volume }) and, where Google classifies it, search_intent. Use it to compare demand for a product across markets: call it once per country with the same keywords. You get one item per keyword you asked for, in your order. A keyword Google holds no volume for comes back with search_volume: null, never 0, so a null means unknown and a 0 means Google reports none. Every null row says why in null_reason: "withheld" means Google stopped publishing volume for the term (since December 2023 it withholds many health and other sensitive terms, such as "shingles" or "herniated disc"), and such a row carries last_reported ({ year, month, search_volume }, the last month Google published a figure) with an empty monthly_searches; "no_data" means Google holds no figure at all (very rare or unknown terms). For relative interest in a withheld term, use /v1/google_trends/explore, or /v1/naver/search-trend in Korea. When no keyword has current volume the call returns 404 and costs 0 credits; its message lists the last published figures. Volumes are Google's own rounded monthly averages and are refreshed monthly, so results are cached for 24 hours. Typical latency is 2 seconds. Priced at a flat 16 credits per call whatever the keyword count, so send all 20 at once.

get/google/keyword-volume

Request

  • Base URL: https://www.socialcrawl.dev/v1
  • URL: https://www.socialcrawl.dev/v1/google/keyword-volume
  • Auth: API key in header x-api-key

Query parameters

keywordsstring required

1-20 comma-separated keywords (e.g. 'lip gloss,lip oil'). Each keyword may be up to 80 characters. Duplicates are ignored. More than 20 keywords, or a keyword over 80 characters, is rejected with a free 400 before the request is billed.

locationstring

Country as an ISO code ('US', 'GB', 'KR'), a full country name ('United Kingdom', 'South Korea') or a numeric location code ('2826'). Defaults to the United States. Volume is published for 94 countries; any other location is rejected with a free 400 naming the accepted forms.

languagestring

Language code ('en', 'de', 'ko') the keywords are searched in. Defaults to the first language listed for the country: Germany is 'de' and Belgium is 'fr', but Vietnam, Indonesia, India, Malaysia, Pakistan, the Philippines, Hong Kong and Singapore default to 'en', so pass their local language (e.g. 'vi', 'id', 'hi') explicitly. A language the country does not hold (Germany in English) is rejected with a free 400 listing the ones it does.

Headers

Cache-Controlstring

Send no-cache to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the no-cache directive triggers this. See the Response Schema guide for details.

Idempotency-Keystring

Optional UUID that makes the request safely retriable. The key is reserved atomically per account before billing. A concurrent retry receives 409 IDEMPOTENCY_IN_PROGRESS with a Retry-After of 1 second while the original is young, growing to a quarter of the time it has been running (at most 30); a crashed reservation expires after 5 minutes. A replay keeps the cached payload immutable except for billing metadata: credits_used becomes 0, idempotent_replay becomes true, and credits_remaining is refreshed to the current balance. A known current balance appears in both the body and X-Credits-Remaining header; no balance row resolves to 0. On a transient lookup failure, body credits_remaining is null and X-Credits-Remaining is omitted. Completed outcomes expire after 24 hours. If the claim store is unavailable, the request fails closed before billing. GET endpoints do not combine idempotent replay with Server-Sent Events: use Accept: application/json when sending this header. The unsupported key-plus-SSE combination is rejected before billing.

Response

Successful response

successboolean required

Whether the request succeeded

platformstring required

Platform name

endpointstring required

API endpoint path

credits_usedinteger required

Number of credits consumed

credits_remaininginteger nullable required

Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction.

request_idstring required

Unique request identifier for support

cachedboolean required

Whether the response was served from cache

idempotent_replayboolean

True only when this response is an idempotency replay

Example response

{
  "success": true,
  "platform": "google",
  "endpoint": "/v1/google/keyword-volume",
  "credits_used": 1,
  "credits_remaining": 4999,
  "request_id": "req-abc123",
  "idempotent_replay": true,
  "meta": {
    "hint": {
      "code": "search_multi",
      "message": "You searched \"matcha\" on 3 platforms one call at a time; /v1/search/multi returns each platform's own search rows in one call at the same price per platform, and a platform with no rows is not charged.",
      "method": "GET",
      "path": "/v1/search/multi?query=matcha&platforms=instagram,tiktok,youtube"
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.