Get Keyword Data
This endpoint retrieves active keywords and their corresponding data within a specified timeframe from the Rank Tracker.
With this endpoint, you can get:
Campaign-wide Data
: By default, this endpoint returns data for all active keywords in a specified campaign.
Group-specific Data
: When you provide a group_id
, this endpoint will return data exclusively for the keywords within the specified group. Additionally, there are special group IDs which can access predefined groups. These are detailed further in the section on query parameters.
Keyword-specific Data
: You can request data for specific keywords within a campaign by supplying their IDs using the keyword_ids
parameter. keyword_ids
should be a comma-separated list of keyword IDs.
Note: Use other parameters like limit
, offset
, order_by
, order_direction
, and search
to further customize the data retrieval as per your needs.
Request
(Required) This parameter specifies the ID of the campaign for which you want to return data.
Please refer to the Quick Start Guide to learn how to retrieve the IDs of your campaigns.
(Required) This parameter specifies the start date of the timeframe for which you want to return the ranking and traffic data in YYYY-MM-DD format.
If you don't specify a start_date
, the default is 30 days before the end_date
.
(Required) This parameter specifies the end date of the timeframe for which you want to return the ranking and traffic data in YYYY-MM-DD format.
If you don't specify an end_date
, the default is the current day.
The IDs of specific groups in the campaign to get keyword data for.
Please refer to the Quick Start Guide to learn how to retrieve the IDs of your groups.
If you do not specify a group_id
, the default value is the All Keywords
group, which means data will be returned for all active keywords in the campaign.
Special Group IDs
There are several special IDs you can use to retrieve specific sets of keywords:
0: Retrieves data for all keywords.
-1: Specifies the Brand folder.
-2: Retrieves keywords that are not grouped by variations.
-3: Targets keywords associated with the Forecast objective.
This parameter allows you to specify the IDs of the keywords for which you want to return data. keyword_ids
should be a comma-separated list of keyword IDs.
Please refer to the Quick Start Guide to learn how to retrieve the IDs of your keywords.
If you do not specify keyword_ids
, the API will return data for all keywords that meet the other specified criteria (e.g. group_id
).
This parameter determines the maximum number of records to return in a single request.
Maximum Value: 1000 records per request
If you do not specify a limit
, the default number of records returned per request will be 100.
This parameter specifies the starting point within the collection of resource results. It's typically used with the limit
parameter to implement pagination.
If you do not specify an offset
, the API will start from the first record.
This parameter enables you to sort the returned data based on a specified field.
The field names you can use to sort data are:
keyword
search_volume
year-over-year
rank
rank_trend
: Sorts the data based on the trend in keyword ranking.rank_trend_impact
: Sorts the data based on the rank trend impact on Visibility.opportunity
: Sorts the data based on the keyword Opportunity score.
This parameter determines the sorting direction of the order_by
field. You can sort the data in either ascending (asc
) or descending (desc
) order.
Note: The order_direction
parameter works in conjunction with the order_by
parameter. Use it to specify the direction of the sort after choosing the field to order by with order_by
.
If you do not specify an order_direction
, the default is asc
.
The search
parameter allows you to filter the results based on a keyword search. The API will return only those records where the keyword matches (fully or partially) the provided search term.
The search parameter is case-insensitive, allowing partial matches irrespective of casing.
Request samples
Responses
[
{
"keyword_id": "<integer>",
"keyword": "<string>",
"main_keyword_id": "<integer>",
"search_intent": "<string>",
"labels": "<string>",
"groups": "<string>",
"serp_data": {
"desktop": [
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
},
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
}
],
"mobile": [
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
},
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
}
],
"percentage_clicks": "<number>"
},
"search_data": {
"year_over_year": "<integer>",
"search_volume": "<integer>",
"monthly_searches": [
{
"search_volume": "<integer>",
"month": "<string>",
"year": "<integer>"
},
{
"search_volume": "<integer>",
"month": "<string>",
"year": "<integer>"
}
]
},
"ranking_data": {
"desktop": {
"rank": "<integer>",
"trend": "<integer>",
"trend_impact": "<integer>",
"best_rank": {
"rank": "<integer>",
"date": "<date>"
}
},
"mobile": {
"rank": "<integer>",
"trend": "<integer>",
"trend_impact": "<integer>",
"best_rank": {
"rank": "<integer>",
"date": "<date>"
}
}
},
"landing_pages": {
"desktop": {
"current": "<string>",
"desired": "<string>"
},
"mobile": {
"current": "<string>",
"desired": "<string>"
}
},
"traffic_data": {
"currency": "<string>",
"ecommerce": {
"transactions": "<integer>",
"revenue": "<integer>"
},
"goals": {
"revenue": "<integer>",
"completions": "<integer>"
},
"sessions": "<integer>"
},
"opportunity": {
"score": "<integer>",
"additional_monthly_sessions": {
"additional_monthly_sessions": "<integer>",
"additional_monthly_revenue": "<integer>",
"equivalent_google_ads_spend": "<integer>",
"avg_cpc": "<double>"
},
"difficulty": "<string>",
"avg_cpc": "<double>"
}
},
{
"keyword_id": "<integer>",
"keyword": "<string>",
"main_keyword_id": "<integer>",
"search_intent": "<string>",
"labels": "<string>",
"groups": "<string>",
"serp_data": {
"desktop": [
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
},
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
}
],
"mobile": [
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
},
{
"position": "<string>",
"feature": "<string>",
"listed": "<boolean>"
}
],
"percentage_clicks": "<number>"
},
"search_data": {
"year_over_year": "<integer>",
"search_volume": "<integer>",
"monthly_searches": [
{
"search_volume": "<integer>",
"month": "<string>",
"year": "<integer>"
},
{
"search_volume": "<integer>",
"month": "<string>",
"year": "<integer>"
}
]
},
"ranking_data": {
"desktop": {
"rank": "<integer>",
"trend": "<integer>",
"trend_impact": "<integer>",
"best_rank": {
"rank": "<integer>",
"date": "<date>"
}
},
"mobile": {
"rank": "<integer>",
"trend": "<integer>",
"trend_impact": "<integer>",
"best_rank": {
"rank": "<integer>",
"date": "<date>"
}
}
},
"landing_pages": {
"desktop": {
"current": "<string>",
"desired": "<string>"
},
"mobile": {
"current": "<string>",
"desired": "<string>"
}
},
"traffic_data": {
"currency": "<string>",
"ecommerce": {
"transactions": "<integer>",
"revenue": "<integer>"
},
"goals": {
"revenue": "<integer>",
"completions": "<integer>"
},
"sessions": "<integer>"
},
"opportunity": {
"score": "<integer>",
"additional_monthly_sessions": {
"additional_monthly_sessions": "<integer>",
"additional_monthly_revenue": "<integer>",
"equivalent_google_ads_spend": "<integer>",
"avg_cpc": "<double>"
},
"difficulty": "<string>",
"avg_cpc": "<double>"
}
}
]