{
  "openapi": "3.0.1",
  "info": {
    "title": "Keyword Search Volume, CPC & Competition (Google Ads data)",
    "description": "Google Ads keyword data in bulk: monthly search volume, CPC, competition, top-of-page bids and 12-month trend for up to 20,000 keywords, any country and language, plus optional keyword ideas. $3 per 1,000 keywords + $0.10 per fresh lookup (up to 1,000 keywords each).",
    "version": "1.0",
    "x-build-id": "bqpZcYea5eltDGE1d"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/fairfetch~keyword-search-volume/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-fairfetch-keyword-search-volume",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/fairfetch~keyword-search-volume/runs": {
      "post": {
        "operationId": "runs-sync-fairfetch-keyword-search-volume",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/fairfetch~keyword-search-volume/run-sync": {
      "post": {
        "operationId": "run-sync-fairfetch-keyword-search-volume",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "keywords"
        ],
        "properties": {
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "One keyword per line, up to 20,000 per run. Duplicates are removed and keywords are lowercased (Google Ads does that too). Google Ads accepts at most 80 characters and 10 words per keyword and rejects symbols such as ! @ % * ( ) ? and emojis: those symbols are removed, and keywords that are too long or contain a letter Google Ads refuses are skipped. Both are listed in the run summary (changedKeywords, invalidKeywords).",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "title": "Location",
            "type": "string",
            "description": "Where the searches happen. Pick a country or type: a two-letter country code (us, gb, de, in ...), a country name, a DataForSEO location code (2840 = United States; states, regions and cities have their own codes) or a full DataForSEO location name such as \"London,England,United Kingdom\". \"worldwide\" = all locations.",
            "default": "us"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Language of the searches, as a Google Ads language code or name (en, de, fr, es, pt, ja, zh-CN, \"German\" ...). Leave empty to use the main language of the location (English for worldwide and unknown locations)."
          },
          "includeMonthlySearches": {
            "title": "Include 12-month history",
            "type": "boolean",
            "description": "Add the monthly search volumes of the last 12 months to every keyword (field monthlySearches, oldest month first). Same price either way.",
            "default": true
          },
          "includeKeywordIdeas": {
            "title": "Add keyword ideas",
            "type": "boolean",
            "description": "Also return related keyword ideas from Google Ads (Keyword Planner style) for your first 20 keywords, each with the same metrics. Ideas are rows with source = \"idea\" and are charged like any other keyword.",
            "default": false
          },
          "maxIdeas": {
            "title": "Max keyword ideas",
            "minimum": 10,
            "maximum": 5000,
            "type": "integer",
            "description": "Upper limit on keyword ideas added (most relevant first, after the minimum volume filter). Ideas that are already in your keyword list are skipped.",
            "default": 100
          },
          "minVolume": {
            "title": "Minimum monthly search volume",
            "minimum": 0,
            "type": "integer",
            "description": "Only keep keywords (and ideas) with at least this average monthly search volume. Skipped keywords are not charged (the lookup fee still applies when Google Ads returned data). 0 = keep all keywords that have data.",
            "default": 0
          },
          "includeKeywordsWithoutData": {
            "title": "Include keywords without data",
            "type": "boolean",
            "description": "Google Ads has no data for some keywords (too rare, restricted or not found). Off (default): they are left out and not charged, and only counted in the run summary. On: they are added with empty metrics (hasData = false) and charged like other rows (a lookup in which no keyword has data has no lookup fee either way). Ignored when a minimum volume is set.",
            "default": false
          },
          "sortBy": {
            "title": "Sort results by",
            "enum": [
              "searchVolume",
              "cpc",
              "competition",
              "keyword",
              "input"
            ],
            "type": "string",
            "description": "Order of the rows in the dataset. Rows are saved after every lookup (up to 1,000 keywords each), so nothing is lost if a run stops early: your keywords come first, sorted within each block of 1,000, then the keyword ideas, sorted the same way. For volume, CPC and competition, rows without that value go last. \"Input order\" keeps your keywords in the order you entered them, with ideas in Google's relevance order.",
            "default": "searchVolume"
          },
          "searchPartners": {
            "title": "Include Google search partners",
            "type": "boolean",
            "description": "Off (default): volumes for Google Search only, as in Keyword Planner. On: Google Search plus search partner sites.",
            "default": false
          },
          "cacheDays": {
            "title": "Re-use results for (days)",
            "minimum": 0,
            "maximum": 30,
            "type": "integer",
            "description": "Search volumes are monthly figures, so if you check the same keywords (same location, language and options) again within this many days, the rows you already paid for in an earlier run are reused instead of asking Google Ads again: same price per row, no lookup fee for them. Other keywords are looked up again. Saved in a key-value store named keyword-search-volume-cache in your account. 0 = always fetch fresh data.",
            "default": 7
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}