Google Ads Search Volume Fresh

Returns search volume, CPC, competition index, and 12-month trend data for up to 1,000 keywords per request. Data comes directly from Google Ads and reflects advertiser-side metrics. Historical data is available for 4 years.

Endpoint

POST https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/task_post

This is the Standard method — set a task, retrieve results when ready. For instant results, use the Live method at /v3/keywords_data/google_ads/search_volume/live/.

Task POST Parameters

Required

Field	Type	Description
keywords	array	Keywords to query. Max 1,000 per request. Max 80 characters per keyword. Max 10 words per phrase. Converted to lowercase.

Location (optional — omit for worldwide results)

Field	Type	Description
location_name	string	Full location name, e.g., "United States" or "London,England,United Kingdom"
location_code	integer	Numeric location code, e.g., 2840 for the United States
location_coordinate	string	GPS coordinates in "latitude,longitude" format

Only one location field is needed.

Language (optional)

Field	Type	Description
language_name	string	Full language name, e.g., "English"
language_code	string	Language code, e.g., "en"

Date Range (optional)

Field	Type	Description
date_from	string	Start date in "yyyy-mm-dd" format. Min 4 years back. Default: 12 months ago.
date_to	string	End date in "yyyy-mm-dd" format. Cannot exceed last month (Google doesn't return current month data).

Other Options

Field	Type	Description
search_partners	boolean	Include Google search partner networks. Default: false.
include_adult_keywords	boolean	Include adult-category keywords. Default: false.
sort_by	string	Sort results by: relevance, search_volume, competition_index, low_top_of_page_bid, high_top_of_page_bid. Default: relevance.
tag	string	Custom task identifier, max 255 characters. Returned in the response data object.
postback_url	string	URL to receive completed results via POST (gzip compressed).
pingback_url	string	URL to receive a GET notification when the task is complete.

Response Structure

The API returns a JSON object with the following top-level fields:

Field	Type	Description
version	string	API version
status_code	integer	General status code (20000 = success)
status_message	string	Human-readable status message
time	string	Total execution time in seconds
cost	float	Total cost of this request in USD
tasks_count	integer	Number of tasks in the response
tasks_error	integer	Number of tasks that returned errors
tasks	array	Array of task result objects

Task Object

Field	Type	Description
id	string	Unique task UUID
status_code	integer	Task-level status code
status_message	string	Task-level status message
time	string	Task execution time
cost	float	Task cost in USD
result_count	integer	Number of keyword results
data	object	Echo of the parameters you submitted
result	array	Keyword result objects (null on task_post, populated on task_get)

Result Object (per keyword)

Field	Type	Description
keyword	string	The queried keyword
location_code	integer	Location code used
language_code	string	Language code used
search_volume	integer	Average monthly searches over the date range
competition	string	Competition level: LOW, MEDIUM, or HIGH
competition_index	integer	Numeric competition score (0–100)
cpc	float	Average CPC in USD
low_top_of_page_bid	float	Lower range bid estimate for top-of-page placement (USD)
high_top_of_page_bid	float	Upper range bid estimate for top-of-page placement (USD)
monthly_searches	array	Monthly search volume breakdown — array of {year, month, search_volume} objects

Code Examples

cURL

login="your_login"
password="your_password"
cred="$(printf ${login}:${password} | base64)"

curl --location --request POST "https://api.dataforseo.com/v3/keywords_data/google_ads/search_volume/task_post" \
  --header "Authorization: Basic ${cred}" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "location_name": "United States",
      "keywords": [
        "buy laptop",
        "cheap laptops for sale",
        "purchase laptop"
      ]
    }
  ]'

Python

from client import RestClient

client = RestClient("your_login", "your_password")

post_data = dict()

post_data[0] = dict(
    location_name="United States",
    language_code="en",
    keywords=[
        "buy laptop",
        "cheap laptops for sale",
        "purchase laptop"
    ]
)

response = client.post("/v3/keywords_data/google_ads/search_volume/task_post", post_data)

if response["status_code"] == 20000:
    task_id = response["tasks"][0]["id"]
    print(f"Task set. ID: {task_id}")
else:
    print(f"Error {response['status_code']}: {response['status_message']}")

Retrieving Results

After setting a task, poll for completion and retrieve results:

# Check which tasks are ready
ready = client.get("/v3/keywords_data/google_ads/search_volume/tasks_ready")

# Retrieve a specific task result
task_id = "your-task-uuid-here"
result = client.get(f"/v3/keywords_data/google_ads/search_volume/task_get/{task_id}")

if result["status_code"] == 20000:
    for keyword_data in result["tasks"][0]["result"]:
        print(keyword_data["keyword"], keyword_data["search_volume"], keyword_data["cpc"])

Pricing Notes

• One request covers 1 to 1,000 keywords at the same price
• Worldwide results (no location specified) are priced separately
• Check the Pricing page for current rates per request