--- metadata: - name: generator content: Diplodoc Platform v5.50.3 alternate: - https://yandex.ru/support2/wordstat/en/content/api-structure.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/support2/wordstat/en/llms.txt # Structure of the API The Wordstat API includes the following methods: - `/v1/getRegionsTree`; - `/v1/topRequests`; - `/v1/dynamics`; - `/v1/regions`. Requests consume the total quota on requests to the service, as well as the personal quota on the number of requests per second. Requests are made using the HTTP POST method. Parameters are passed in JSON format in the request body. To properly process the request body, use the header `Content-type: application/json`. ## `/v1/getRegionsTree` The `/v1/getRegionsTree` method returns a JSON object describing a set of Wordstat-supported regions. Other API methods accept a list of region IDs, you can get them here. Without parameters. Doesn't consume the daily quota on requests. ## `/v1/topRequests` The `/v1/topRequests` method returns the last 30 days data about popular queries containing the specified keyword and queries that are similar to the specified one. #| || **Parameter** | **Description** | **Required** || || `phrase` | Keyword | Yes || || `regions` | A list of IDs of the regions a query was made from. You can get allowable values from the [`/v1/getRegionsTree` method](https://yandex.ru/support2/wordstat/en/content/api-structure.md#/v1/getRegionsTree). By default, queries from any region are counted. | No || || `devices` | A list of device types a query was made from. Possible values: - `all`; - `desktop`; - `phone`; - `tablet`. The default value is `all`. | No || |# Request example: ``` curl -XPOST -H 'Content-type: application/json;charset=utf-8' -H 'Authorization: Bearer ' -d '{"phrase":"яндекс","regions":[213,2],"devices":["phone"]}' https:// api.wordstat.yandex.net/v1/topRequests ``` Response format: the `topRequests` array consisting of key-value pairs (`phrase`: keyword, `count`: number of queries made). {% cut "Response example" %} ``` { "topRequests": [ { "phrase": "yandex", "count": 8275401 }, { "phrase": "yandex games", "count": 632440 }, { "phrase": "yandex maps", "count": 579075 }, { "phrase": "yandex market", "count": 539802 }, { "phrase": "yandex mail", "count": 377566 } ] } ``` {% endcut %} The method uses a single unit of the daily quota on requests. ## `/v1/dynamics` The `/v1/dynamics` method returns the frequency of queries over time for a given keyword. #| || **Parameter** | **Description** | **Required** || || `phrase` | Keyword | Yes || || `period` | The period of aggregation of the number of queries. Possible values: - `monthly`: Details by month; - `weekly`: Details by week; - `daily`: Details by day. | Yes || || `fromDate` | The start of the period data is requested for, in YYYY-MM-DD format. If details by day are selected, you'll get data for the last 60 days. If details by week and month are selected, you'll get data since January 1, 2018. For `period: monthly`, this parameter must contain the first day of the month. For `period: weekly`, this parameter must contain a date that corresponds to a Monday. | Yes || || `toDate` | The end of the period data is requested for, in YYYY-MM-DD format. For `period: monthly`, this parameter must contain the last day of the month. For `period: weekly`, this parameter must contain a date that corresponds to a Sunday. By default, the following values are used: - For `period: monthly`: The end of the last month. - For `period: weekly`: The last Sunday. - For `period: daily`: Yesterday's date. | No || || `regions` | A list of IDs of the regions a query was made from. You can get allowable values from the [`/v1/getRegionsTree` method](https://yandex.ru/support2/wordstat/en/content/api-structure.md#/v1/getRegionsTree). By default, queries from any region are counted. | No || || `devices` | A list of device types a query was made from. Possible values: - `all`; - `desktop`; - `phone`; - `tablet`. The default value is `all`. | No || |# Request example: ``` {"phrase":"yandex","period":"weekly","fromDate":"2025-02-03","toDate":"2025-04-06","regions":[213,2],"devices":["phone"]} ``` Response format: the `dynamics` array with the date (`date`), the total number of queries containing the given keyword (`count`), and the share of the number of such queries from the total number of queries to Yandex. {% cut "Response example" %} ``` { "dynamics": [ { "date": "2025-02-03", "count": 1910301, "share": 0.6030092668804485 }, { "date": "2025-02-10", "count": 1926557, "share": 0.6092331204174273 }, { "date": "2025-02-17", "count": 1905623, "share": 0.6088345666509491 }, { "date": "2025-02-24", "count": 1897645, "share": 0.6019076028335435 }, { "date": "2025-03-03", "count": 1879813, "share": 0.6006963056742451 }, { "date": "2025-03-10", "count": 1931583, "share": 0.5929364330818319 }, { "date": "2025-03-17", "count": 1933021, "share": 0.585401132607149 }, { "date": "2025-03-24", "count": 1953561, "share": 0.593108598108686 }, { "date": "2025-03-31", "count": 1909107, "share": 0.5748788349658039 } ] } ``` {% endcut %} The method uses a single unit of the daily quota on requests. ## /v1/regions The `/v1/regions` method returns the distribution of the number of queries containing the given keyword globally by region for the last 30 days. #| || **Parameter** | **Description** | **Required** || || `phrase` | Keyword | Yes || || `regionType` | Show query distribution only by city, only by region, or everywhere. Possible values: - `cities`; - `regions`; - `all`. The default value is `all`. | No || || `devices` | A list of device types a query was made from. Possible values: - `all`; - `desktop`; - `phone`; - `tablet`. The default value is `all`. | No || |# Request example: ``` {"phrase":"yandex","regionType":"cities","devices":["phone"]} ``` Response format: the `regions` array with the region ID (`regionId`), the number of queries containing the given keyword in the region (`count`), the share from all queries to Yandex in the region (`share`), and the interest index (as a percentage): the ratio between the share of the selected queries in the region and their share across the country (`affinityIndex`). {% cut "Response example" %} ``` { "regions": [ { "regionId": 2, "count": 2330855, "share": 0.5818950367758946, "affinityIndex": 123.75386731541778 }, { "regionId": 4, "count": 113869, "share": 0.48076034011126784, "affinityIndex": 102.24516034763612 }, { "regionId": 11268, "count": 3160, "share": 0.24667996864978625, "affinityIndex": 52.46238269843529 }, { "regionId": 5, "count": 126737, "share": 0.5177023552746863, "affinityIndex": 110.10176154538539 }, { "regionId": 6, "count": 141108, "share": 0.5302251202210722, "affinityIndex": 112.7650263846661 }, { "regionId": 11270, "count": 2763, "share": 0.19726428773884294, "affinityIndex": 41.95295877786469 }, { "regionId": 21510, "count": 12568, "share": 0.5833962313197623, "affinityIndex": 124.0731321632944 } ] } ``` {% endcut %} The method uses two units of the daily quota on requests.