get/positions_2/history
Method description
Use the method to get keyword ranking history.
The method is not applicable to the archived projects.
Method parameters
Parameter |
Type |
Description |
Default |
Mandatory |
project_id |
int |
project ID |
|
regions_indexes |
array(int) |
Region index |
|
dates |
array of date |
Random rank check dates
(dates is mandatory, if date1 and date2 are not specified)
|
|
date1, date2 |
date |
The first and the last date of period
(date1 and date2 are mandatory, if dates isn't specified)
|
|
Additional |
fields |
array of fields
of keywords
|
"Keyword" object fields to return |
|
competitors_ids |
array(int) |
IDs of competitors added in the project settings |
|
type_range |
enum(0, 1, 2, 3, 4, 5, 6, 7, 100) |
Period
Available values:
- 0 - entire period
- 1 - only updates
- 2 - period up to 31 dates
- 3 - two dates
- 4 - one date
- 5 - the last date of each month
- 6 - dates at equal intervals
- 7 - two last ranking updates
- 100 - random dates (can be used with the dates parameter only)
|
2 |
count_dates |
int |
A maximum number of dates to return (up to 31) |
|
only_exists_first_date |
int boolean |
Display only keywords from the first check in the applied period |
|
show_headers |
int boolean |
Include result headers in result |
0 |
show_exists_dates |
int boolean |
Include dates of keyword ranking checks |
0 |
show_visitors |
int boolean |
Include a total number of visits for every date |
0 |
show_top_by_depth |
int |
Include keyword distribution across the applied TOP for every rank check |
0 |
positions_fields |
array('position', 'snippet', 'relevant_url', 'visitors') |
Select columns with the rank check results:
- position - keyword rank
- snippet - snippet
- relevant_url - relevant page
- visitors - visit count
|
|
filter_by_dynamic |
set('>', '<', '=') |
Filter by keywords that improved/dropped/didn't change their rankings between the first and the last date of the
applied period
* can be used to get keyword rankings from one project, of one location for two dates or more
|
|
filter_by_positions |
array of array(int, int) |
Filter by keywords with the rankings checked during the applied period |
|
View in API explorer
Returned data
Parameter |
Type |
Description |
result (object) |
keywords |
array of keywords |
Keyword ranking report and other keyword fields |
keywords.positionsData |
object(qualifiers => object) |
Rank check data |
headers |
array |
Result headers (if show_headers = 1) |
existsDates |
array(date) |
Dates when keyword rankings were checked (if show_exists_dates = 1) |
visitors |
object(qualifiers => object) |
Total visit count for every rank check (if show_visitors = 1) |
tops |
object(qualifiers => object) |
Keyword distribution across the applied TOP for every rank check (if show_top_by_depth = N) |
result.keywords[N].positionsData[qualifiers] |
position |
int or string('--') |
Keyword rank |
relevant_url |
string |
Relevant page |
visitors |
int |
Visit count |
result.headers (if show_headers = 1) |
fieldsLabels |
array |
Objects of requested field headers (fields parameter) |
positionsFields |
array |
Matches the positions_fields parameter |
dates |
array |
Dates of ranking checks included in the report |
projects |
array |
Projects (competitors) with search engines and locations |
result.visitors (if show_visitors = 1) |
%Y-d-m:project_id:region_index% |
int |
Visit count by qualifiers |
result.tops (if show_top_by_depth = N) |
%Y-d-m:project_id:region_index% |
int |
Keyword percentage in TOP-N by qualifiers |