Keyword Suggestions (Live) Fresh

The Keyword Suggestions endpoint returns search queries that include your specified seed keyword. It uses a full-text search algorithm — results contain the seed term with additional words before, after, or within the phrase. Word order in the result may differ from the seed.

Endpoint: POST https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live

Datasource: DataForSEO Keyword Database

How the Algorithm Works

Given seed keyword: "keyword research"

Returned suggestions include:

• "google research keyword"
• "how to do keyword research"
• "keyword competitor research"
• "how to do keyword research for content marketing"

Each returned keyword includes: search volume (last month), 12-month search volume trend, CPC, competition score, and keyword difficulty.

Request Parameters

Field	Type	Required	Description
keyword	string	Yes	Seed keyword. UTF-8. Converted to lowercase. Max 700 characters.
location_name	string	No	Full location name (e.g., "United Kingdom"). Use if not specifying location_code. Omit both to get global results.
location_code	integer	No	Location code (e.g., 2840 for USA). Use if not specifying location_name.
language_name	string	No	Full language name (e.g., "English"). Defaults to language with most keyword records for the location if omitted.
language_code	string	No	Language code (e.g., "en").
include_seed_keyword	boolean	No	If true, returns data for the seed keyword in seed_keyword_data. Default: false.
include_serp_info	boolean	No	If true, returns serp_info (SERP features, result count) per keyword. Default: false.
include_clickstream_data	boolean	No	If true, returns clickstream-based search volume, gender/age distribution. Doubles the request cost. Default: false.
exact_match	boolean	No	If true, results contain the exact phrase (with possible words before/after). Default: false.
ignore_synonyms	boolean	No	If true, only core keywords returned — highly similar variants excluded. Default: false.
filters	array	No	Up to 8 filter conditions. Operators: =, <>, >, >=, <, <=, in, not_in, like, ilike, regex.
order_by	array	No	Sort rules. Max 3. Example: ["keyword_info.search_volume,desc"]. Default: by search volume descending.
limit	integer	No	Max keywords returned. Default: 100. Max: 1000.
offset	integer	No	Results offset. Default: 0. For >10,000 results, use offset_token instead.
offset_token	string	No	Token from previous response for paginating past 10,000 results. Overrides all other parameters except limit.
tag	string	No	Custom task identifier. Max 255 characters. Returned in data object of response.

Filter Examples

["keyword_info.search_volume", ">", 0]

[
  ["keyword_info.search_volume", "in", [0, 1000]],
  "and",
  ["keyword_info.competition_level", "=", "LOW"]
]

[
  ["keyword_info.search_volume", ">", 100],
  "and",
  [
    ["keyword_info.cpc", "<", 0.5],
    "or",
    ["keyword_info.high_top_of_page_bid", "<=", 0.5]
  ]
]

Response Structure

Field	Type	Description
version	string	API version
status_code	integer	General status code
status_message	string	General informational message
time	string	Execution time in seconds
cost	float	Total cost in USD
tasks_count	integer	Number of tasks in the array
tasks_error	integer	Number of tasks returned with errors
tasks[].id	string	Task UUID
tasks[].result[].seed_keyword	string	Your input keyword
tasks[].result[].seed_keyword_data	object	Metrics for the seed keyword (when include_seed_keyword: true)
tasks[].result[].total_count	integer	Total matching keywords in database
tasks[].result[].items_count	integer	Keywords returned in this response
tasks[].result[].offset_token	string	Token for next page of results
tasks[].result[].items[]	array	Keyword suggestions with metrics

Item Fields (per keyword)

Field	Type	Description
keyword	string	The suggested keyword
keyword_info.search_volume	integer	Average monthly searches
keyword_info.competition	float	Competition score 0–1 (Google Ads data)
keyword_info.competition_level	string	LOW, MEDIUM, or HIGH
keyword_info.cpc	float	Average cost-per-click in USD
keyword_info.low_top_of_page_bid	float	Min bid for top-of-page placement
keyword_info.high_top_of_page_bid	float	Max bid for top-of-page placement
keyword_info.monthly_searches	array	Search volume per month for past 12 months
keyword_info.categories	array	Product/service category tags
keyword_properties.keyword_difficulty	integer	Difficulty score 0–100 (log scale)
keyword_properties.core_keyword	string	Main keyword in synonym cluster
keyword_properties.detected_language	string	Language identified by the system
keyword_properties.words_count	integer	Word count of the keyword
search_intent_info.main_intent	string	informational, navigational, commercial, or transactional
search_intent_info.foreign_intent	array	Secondary intents
serp_info.serp_item_types	array	SERP feature types present for the keyword
serp_info.se_results_count	string	Number of organic results
avg_backlinks_info.backlinks	float	Average backlinks among top-10 ranking pages
avg_backlinks_info.referring_domains	float	Average referring domains among top-10

cURL Example

curl --request POST \
  --url https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live \
  --header 'Authorization: Basic BASE64(login:password)' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "keyword": "local seo",
      "location_code": 2840,
      "language_code": "en",
      "limit": 20,
      "include_seed_keyword": true,
      "filters": [
        ["keyword_info.search_volume", ">", 100],
        "and",
        ["keyword_info.competition_level", "<>", "HIGH"]
      ],
      "order_by": ["keyword_info.search_volume,desc"]
    }
  ]'

Python Example

import requests
from requests.auth import HTTPBasicAuth
import json

def keyword_suggestions(seed, location_code=2840, language_code="en", limit=100, min_volume=0):
    payload = [{
        "keyword": seed,
        "location_code": location_code,
        "language_code": language_code,
        "limit": limit,
        "include_seed_keyword": True,
        "filters": [["keyword_info.search_volume", ">", min_volume]],
        "order_by": ["keyword_info.search_volume,desc"]
    }]

    response = requests.post(
        "https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_suggestions/live",
        auth=HTTPBasicAuth("your_login", "your_password"),
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload)
    )

    data = response.json()
    result = data["tasks"][0]["result"][0]

    keywords = []
    for item in result["items"]:
        keywords.append({
            "keyword": item["keyword"],
            "search_volume": item["keyword_info"]["search_volume"],
            "cpc": item["keyword_info"]["cpc"],
            "competition_level": item["keyword_info"]["competition_level"],
            "difficulty": item["keyword_properties"]["keyword_difficulty"],
            "intent": item.get("search_intent_info", {}).get("main_intent")
        })

    return keywords

# Usage
results = keyword_suggestions("local seo", min_volume=100)
for kw in results:
    print(f"{kw['keyword']} | Vol: {kw['search_volume']} | KD: {kw['difficulty']} | Intent: {kw['intent']}")

Notes

• Keywords are converted to lowercase before processing.
• The % character in keywords must be encoded as %25; + as %2B.
• offset_token pagination is recommended for retrieving more than 10,000 results. When offset_token is set, all other parameters except limit are ignored.
• Enabling include_clickstream_data doubles the cost of the request.