{
  "openapi": "3.0.1",
  "info": {
    "title": "Google SERP and Keyword Research API - DataForSEO",
    "description": "Google SERP API and keyword research with DataForSEO: live organic rankings, Google Ads search volume, CPC and competition, keyword ideas with difficulty and intent, keywords any domain ranks for, and backlink summaries. Export to JSON, CSV or Excel. Bring your own key.",
    "version": "0.1",
    "x-build-id": "sh8Q24L7of46iZnH9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nabeelbaghoor~google-serp-keyword-research-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nabeelbaghoor-google-serp-keyword-research-api",
        "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/nabeelbaghoor~google-serp-keyword-research-api/runs": {
      "post": {
        "operationId": "runs-sync-nabeelbaghoor-google-serp-keyword-research-api",
        "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/nabeelbaghoor~google-serp-keyword-research-api/run-sync": {
      "post": {
        "operationId": "run-sync-nabeelbaghoor-google-serp-keyword-research-api",
        "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",
        "properties": {
          "mode": {
            "title": "What to do",
            "enum": [
              "serpOrganic",
              "searchVolume",
              "keywordIdeas",
              "rankedKeywords",
              "backlinksSummary"
            ],
            "type": "string",
            "description": "Google organic SERP runs a live Google search for each keyword and returns every ranking result. Google Ads search volume returns monthly search volume, CPC, competition and 12 months of history for up to 1000 keywords per call. Keyword ideas suggests related keywords with volume, CPC, difficulty and intent from the DataForSEO Labs database. Ranked keywords lists the keywords a domain or page ranks for in Google, with position and estimated traffic. Backlinks summary returns backlink and referring domain counts for each domain or page.",
            "default": "serpOrganic"
          },
          "keywords": {
            "title": "Keywords",
            "type": "array",
            "description": "SERP, search volume and keyword ideas modes. One keyword per line. SERP: each keyword is one live search (up to 700 characters). Search volume: up to 1000 keywords per call, each up to 80 characters and 10 words. Keyword ideas: up to 200 seed keywords in one request.",
            "items": {
              "type": "string"
            }
          },
          "targets": {
            "title": "Domains or page URLs",
            "type": "array",
            "description": "Ranked keywords and backlinks summary modes. One per line: a domain such as example.com (without https:// or www.), a subdomain, or a full page URL such as https://example.com/blog/post. Each target is one request.",
            "items": {
              "type": "string"
            }
          },
          "locationCode": {
            "title": "Location code",
            "minimum": 1,
            "type": "integer",
            "description": "DataForSEO location code, for example 2840 United States, 2826 United Kingdom, 2276 Germany, 2124 Canada, 2036 Australia, 2356 India. Required for SERP and keyword ideas (or give a location name); optional for search volume and ranked keywords. Not used by backlinks summary.",
            "default": 2840
          },
          "locationName": {
            "title": "Location name",
            "type": "string",
            "description": "Used only when the location code is empty. A DataForSEO location name such as United States or London,England,United Kingdom."
          },
          "languageCode": {
            "title": "Language code",
            "type": "string",
            "description": "Search engine language code such as en, de, fr, es or zh-TW. Optional; leave empty to let DataForSEO pick the main language of the location.",
            "default": "en"
          },
          "device": {
            "title": "Device",
            "enum": [
              "desktop",
              "mobile"
            ],
            "type": "string",
            "description": "SERP mode only. Desktop or mobile Google results.",
            "default": "desktop"
          },
          "os": {
            "title": "Operating system",
            "enum": [
              "default",
              "windows",
              "macos",
              "android",
              "ios"
            ],
            "type": "string",
            "description": "SERP mode only. Windows or macOS for desktop, Android or iOS for mobile.",
            "default": "default"
          },
          "depth": {
            "title": "Results per keyword (depth)",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "SERP mode only. How many results to read for each keyword, up to 200. DataForSEO bills each 10 results as one SERP page, so 100 costs about ten times as much as 10.",
            "default": 10
          },
          "seDomain": {
            "title": "Google domain",
            "type": "string",
            "description": "SERP mode only. Optional Google domain such as google.co.uk or google.de. DataForSEO picks one from the location when empty."
          },
          "organicOnly": {
            "title": "Organic results only",
            "type": "boolean",
            "description": "SERP mode only. Keep only organic results. Untick to also get ads, featured snippets, people also ask, local packs, AI overviews and every other SERP element as rows.",
            "default": true
          },
          "searchPartners": {
            "title": "Include search partners",
            "type": "boolean",
            "description": "Search volume mode only. Include Google search partner sites in the volume.",
            "default": false
          },
          "dateFrom": {
            "title": "Date from",
            "type": "string",
            "description": "Search volume mode only. Start of the monthly history (YYYY-MM-DD, up to 4 years back). Default is the past 12 months."
          },
          "dateTo": {
            "title": "Date to",
            "type": "string",
            "description": "Search volume mode only. End of the monthly history (YYYY-MM-DD). Google Ads has no data for the current month."
          },
          "volumeSortBy": {
            "title": "Search volume sort order",
            "enum": [
              "relevance",
              "search_volume",
              "competition_index",
              "low_top_of_page_bid",
              "high_top_of_page_bid"
            ],
            "type": "string",
            "description": "Search volume mode only. Sort order of the results, descending.",
            "default": "relevance"
          },
          "closelyVariants": {
            "title": "Phrase match",
            "type": "boolean",
            "description": "Keyword ideas only. Phrase-match search instead of broad match.",
            "default": false
          },
          "ignoreSynonyms": {
            "title": "Ignore synonyms",
            "type": "boolean",
            "description": "Keyword ideas and ranked keywords. Return only core keywords and drop highly similar variants.",
            "default": false
          },
          "includeSerpInfo": {
            "title": "Include SERP info",
            "type": "boolean",
            "description": "Keyword ideas only. Add SERP data (result count, SERP features, check URL) to each keyword idea.",
            "default": false
          },
          "ideaSortBy": {
            "title": "Keyword ideas sort order",
            "enum": [
              "relevance,desc",
              "keyword_info.search_volume,desc",
              "keyword_info.search_volume,asc",
              "keyword_info.cpc,desc",
              "keyword_info.competition,desc"
            ],
            "type": "string",
            "description": "Keyword ideas only. How ideas are sorted before the result limit applies.",
            "default": "relevance,desc"
          },
          "minSearchVolume": {
            "title": "Minimum search volume",
            "minimum": 0,
            "type": "integer",
            "description": "Keyword ideas and ranked keywords. Only keywords with at least this monthly search volume."
          },
          "rankedItemTypes": {
            "title": "Result types",
            "type": "array",
            "description": "Ranked keywords only. Which SERP result types to include. Empty means organic and paid, the provider default.",
            "items": {
              "type": "string",
              "enum": [
                "organic",
                "paid",
                "featured_snippet",
                "local_pack",
                "ai_overview_reference"
              ],
              "enumTitles": [
                "Organic",
                "Paid",
                "Featured snippet",
                "Local pack",
                "AI overview reference"
              ]
            }
          },
          "historicalSerpMode": {
            "title": "Ranking status",
            "enum": [
              "live",
              "lost",
              "all"
            ],
            "type": "string",
            "description": "Ranked keywords only. Current rankings, rankings lost since the last check, or both.",
            "default": "live"
          },
          "maxRank": {
            "title": "Maximum position",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Ranked keywords only. Only keywords where the target ranks at this position or better, for example 10 for page one."
          },
          "rankedSortBy": {
            "title": "Ranked keywords sort order",
            "enum": [
              "ranked_serp_element.serp_item.rank_group,asc",
              "keyword_data.keyword_info.search_volume,desc",
              "keyword_data.keyword_info.cpc,desc",
              "keyword_data.keyword_info.competition,desc"
            ],
            "type": "string",
            "description": "Ranked keywords only. How keywords are sorted before the result limit applies.",
            "default": "ranked_serp_element.serp_item.rank_group,asc"
          },
          "includeSubdomains": {
            "title": "Include subdomains",
            "type": "boolean",
            "description": "Backlinks summary only. Count backlinks to subdomains of the target too.",
            "default": true
          },
          "includeIndirectLinks": {
            "title": "Include indirect links",
            "type": "boolean",
            "description": "Backlinks summary only. Count links to pages that redirect to the target or name it as canonical.",
            "default": true
          },
          "excludeInternalBacklinks": {
            "title": "Exclude internal backlinks",
            "type": "boolean",
            "description": "Backlinks summary only. Leave out links from other subdomains of the same domain.",
            "default": true
          },
          "backlinksStatusType": {
            "title": "Backlink status",
            "enum": [
              "live",
              "all",
              "lost"
            ],
            "type": "string",
            "description": "Backlinks summary only. Count live backlinks, lost backlinks, or all.",
            "default": "live"
          },
          "rankScale": {
            "title": "Rank scale",
            "enum": [
              "one_thousand",
              "one_hundred"
            ],
            "type": "string",
            "description": "Backlinks summary only. Scale of the backlink rank value.",
            "default": "one_thousand"
          },
          "maxResults": {
            "title": "Maximum results",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "The most rows this run returns and charges for. It also stops further DataForSEO calls once reached, which keeps your DataForSEO spend in check.",
            "default": 100
          },
          "requestsPerMinute": {
            "title": "Requests per minute",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Pacing. DataForSEO allows 2000 calls a minute and 30 at once; Google Ads search volume is limited to 12 a minute and is always paced to that.",
            "default": 600
          },
          "apiKey": {
            "title": "API login",
            "type": "string",
            "description": "Your DataForSEO API login (the email shown on app.dataforseo.com/api-access). Stored as a secret and sent only in the HTTP Basic Authorization header. You can instead set the DATA_API_KEY environment secret to login:password."
          },
          "apiSecret": {
            "title": "API password",
            "type": "string",
            "description": "Your DataForSEO API password from app.dataforseo.com/api-access. It is generated by DataForSEO and is not your account password. You can instead set the DATA_API_SECRET environment secret."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}