{
  "openapi": "3.0.1",
  "info": {
    "title": "YouTube Search Scraper: Country & Language Targeting",
    "description": "YouTube Search Scraper: Country & Language Targeting extracts YouTube search results by country and language, including titles, channels, URLs, views, likes, publish dates, thumbnails, and metadata. Ideal for localized SEO, content research, and competitor analysis.",
    "version": "0.1",
    "x-build-id": "KdNqFQdfpWOSDbqSB"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapio~youtube-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapio-youtube-search-scraper",
        "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/scrapio~youtube-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapio-youtube-search-scraper",
        "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/scrapio~youtube-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapio-youtube-search-scraper",
        "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": {
          "queries": {
            "title": "🔎 Search terms",
            "type": "array",
            "description": "One search term per line. Each term is searched separately in every country you list below. Example: « coffee recipe » across US + BR + JP = three searches, three ranked result sets.",
            "items": {
              "type": "string"
            },
            "default": [
              "coffee recipe"
            ]
          },
          "targetCountries": {
            "title": "🌍 Search from these countries",
            "type": "array",
            "description": "Two-letter country codes (ISO 3166), one per line — e.g. US, GB, DE, BR, JP, IN, MX. Each one is a separate residential exit IP, so each returns that country's real result set. Measured overlap with the US result set on an identical query: DE 2/8, BR 2/8, JP 3/8. More countries = more searches = proportionally more proxy traffic. Default is US only.",
            "items": {
              "type": "string"
            },
            "default": [
              "US"
            ]
          },
          "interfaceLanguage": {
            "title": "🗣️ Interface language",
            "type": "string",
            "description": "« auto » sends YouTube's interface language that matches each country (DE→de, BR→pt, JP→ja). This is a second, independent lever on the result set — measured overlap with an English search on the same query: ja 5/8, pt 5/8, de 6/8. Enter a language code (e.g. « es ») to force one language for every country, or « off » to always search in English.",
            "default": "auto"
          },
          "resultsPerCountry": {
            "title": "📊 Results per country",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "How many results to pull for each search term in each country. A run costs roughly this number × terms × countries rows. 10–20 is plenty to see how a keyword's ranking differs between markets. Note that YouTube's search pages thin out long before 2000 rows, so very high values return less than requested.",
            "default": 10
          },
          "crossCountryRollup": {
            "title": "🗺️ Add cross-country presence columns",
            "type": "boolean",
            "description": "Adds `countriesFound`, `rankByCountry`, `missingFromCountries`, `bestRank`, `bestRankCountry` and `isCountryExclusive` to every row — i.e. which markets surfaced this video and at what position. Default on.",
            "default": true
          },
          "mergeCountryRows": {
            "title": "🔗 One row per video instead of one per country",
            "type": "boolean",
            "description": "Off (default): one row per video per country, so you see each country's ranked list. On: each video appears once, at its best rank, with the per-country positions kept in `rankByCountry`. Turn this on when you want a deduplicated list rather than a per-market ranking.",
            "default": false
          },
          "sortBy": {
            "title": "↕️ Sort results by",
            "enum": [
              "relevance",
              "date",
              "viewCount",
              "rating"
            ],
            "type": "string",
            "description": "Encoded into YouTube's real `sp=` search parameter, so it genuinely reorders results. Applied identically in every country.",
            "default": "relevance"
          },
          "uploadDate": {
            "title": "📅 Uploaded within",
            "enum": [
              "",
              "lastHour",
              "today",
              "thisWeek",
              "thisMonth",
              "thisYear"
            ],
            "type": "string",
            "description": "Restrict every country's search to videos published in this window.",
            "default": ""
          },
          "duration": {
            "title": "⏱️ Video length",
            "enum": [
              "",
              "short",
              "medium",
              "long"
            ],
            "type": "string",
            "description": "Short is under 4 minutes, medium 4–20, long over 20. Verified live: the « short » filter returned videos of 13–144 seconds where the unfiltered search returned 7,341–43,200 seconds.",
            "default": ""
          },
          "type": {
            "title": "📺 Result kind",
            "enum": [
              "video",
              "channel",
              "playlist",
              "movie"
            ],
            "type": "string",
            "description": "Videos, channels, playlists or movies. Channel and playlist searches return channel/playlist rows (`UC…` / `PL…` ids) rather than videos, so the video-only columns (views, length, likes) are empty for them.",
            "default": "video"
          },
          "metadataDepth": {
            "title": "💰 Metadata depth (this drives the cost)",
            "enum": [
              "flat",
              "full"
            ],
            "type": "string",
            "description": "« Search page » costs about 2 KB of proxy traffic per row and returns rank, title, channel, views, length, verified badge and the search snippet. « Full video » additionally opens every single video for likes, comment count, subscriber count, exact publish time, tags and the complete description — at about 587 KB of residential traffic PER VIDEO, roughly 280× more expensive. Fields that only exist on the full tier are left empty (never zero-filled) on the search-page tier.",
            "default": "flat"
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Country targeting only works over residential exits, so this actor uses Apify Residential proxies for the searches themselves and OVERRIDES the selection here — that override is logged at the start of every run. Anything you set is kept as a fallback for countries where no residential exit is available.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "debug": {
            "title": "🐛 Verbose logging",
            "type": "boolean",
            "description": "Logs each country's search attempts, the generated `sp=` parameter and any yt-dlp error text. Useful when a country returns nothing.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}