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 |
|
|
Keyword |
Yes |
|
|
A list of IDs of the regions a query was made from. You can get allowable values from the |
No |
|
|
A list of device types a query was made from. Possible values:
The default value is |
No |
Request example:
curl -XPOST -H 'Content-type: application/json;charset=utf-8' -H 'Authorization: Bearer <oauth-token>' -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).
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
}
]
}
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 |
|
|
Keyword |
Yes |
|
|
The period of aggregation of the number of queries. Possible values:
|
Yes |
|
|
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. |
Yes |
|
|
The end of the period data is requested for, in YYYY-MM-DD format.
|
No |
|
|
A list of IDs of the regions a query was made from. You can get allowable values from the |
No |
|
|
A list of device types a query was made from. Possible values:
The default value is |
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.
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
}
]
}
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 |
|
|
Keyword |
Yes |
|
|
Show query distribution only by city, only by region, or everywhere. Possible values:
The default value is |
No |
|
|
A list of device types a query was made from. Possible values:
The default value is |
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).
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
}
]
}
The method uses two units of the daily quota on requests.