get/positions_2/history

Method description

Use to get keyword ranking history.

The method is not applicable to the archived projects.

Method parameters

Parameter Type Description Default
Required
project_id int project ID
regions_indexes array(int) Region index
dates array of date Random rank check dates
(dates is required, if date1 and date2 are not set)
date1, date2 date The first and the last date of period
(date1 and date2 are required, if dates isn't set)
Additional
fields array 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 - whole 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 results headers in result 1
show_exists_dates int boolean Include dates of keyword ranking checks 1
show_visitors int boolean Include a total number of visits for every date 1
show_top_by_depth int Include keyword distribution across the applied TOP for every rank check 1
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 Results 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 to 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

FAQ