Get Keyword Data

GET

https://apigw.seomonitor.com/v3/rank-tracker/v3.0/keywords

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

Authorization

Add parameter in header

Example:

X-Token: ********************

Query Params

campaign_id

integer

required

(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.

Example:

start_date

string

required

(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.

Example:

end_date

string

required

(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.

Example:

group_id

string

optional

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 data for ungrouped keywords.
-3: Targets keywords associated with the Forecast objective.

Example:

include_all_groups

string

optional

This parameter controls whether folder and smart group IDs are included in the output. Enabling this option (true) can substantially slow down the response time. If not specified, the default behavior excludes folders and smart groups, focusing the response on active keywords in regular groups only.

Example:

keyword_ids

string

optional

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).

Example:

limit

integer

optional

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.

Example:

offset

integer

optional

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.

Example:

order_by

string

optional

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.

Example:

order_direction

string

optional

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.

Example:

string

optional

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.

Example:

Header Params

string

required

Example:

application/json

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location -g --request GET 'https://apigw.seomonitor.com/v3/rank-tracker/v3.0/keywords?campaign_id={{campaign_id}}&start_date={{start_date}}&end_date={{end_date}}&group_id={{group_id}}&include_all_groups={{include_all_groups}}&keyword_ids={{keyword_ids}}&limit={{limit}}&offset={{offset}}&order_by={{order_by}}&order_direction={{order_direction}}&search={{search}}' \
--header 'Accept: application/json'

Responses

🟢200List of keywords details.

application/json

Body

array of:

keyword_id

integer

optional

The unique ID used to identify and reference the keyword in the system. It can be stored and used in other endpoints for filtering.

keyword

string

optional

The exact keyword phrase.

main_keyword_id

integer

optional

The ID of the main keyword, if the current keyword is aggregated under another keyword as its close variation.

search_intent

string

optional

The search intent of the keyword. Possible values: informational, commercial, or transactional.

labels

string

optional

The label associated with the keyword, either manually or automatically applied, that indicate specific attributes or characteristics of a keyword. Possible values: automatic labels: misspelled,'low relevance, brands, localized. for keywords labeled as seasonal in the platform, the endpoint will return one of the following possible values: in_full_season, out_of_season, season_approaching. custom labels: User-defined label name.

groups

string

optional

The group_ids of the groups this keyword is included in.

serp_data

object

optional

Parent field containing the SERP features data for the keyword for the last day of the selected timeframe, segmented by device. Please refer to the Quick Start Guide for the complete feature name of each abbreviation.

desktop

array [object {3}]

optional

Parent field containing the SERP features data for desktop devices.

mobile

array [object {3}]

optional

Parent field containing the SERP features data for mobile devices.

percentage_clicks

string

optional

The percentage of searches that end up clicking on organic results, after discounting the searches satisfied by SERP features. Blended metric between desktop and mobile searches.

search_data

object

optional

Parent field containing the data related to Google search volumes.

search_volume

integer

optional

The latest average 12-month search volume as provided by Google Ads.

year_over_year

number

optional

A numeric value representing the last month's search volume divided by the search volume of the same month of the previous year. E.g. +49% year-over-year search trend would be represented as 1.49. The returned values will be capped at 10, which represents "newcomers" (keywords that registered very low search volumes in the previous year).

monthly_searches

array [object {3}]

optional

An array of objects containing the search volumes for each of the previous 13 months as provided by Google Ads.

ranking_data

object

optional

Parent field containing all the Google ranking data associated with the keyword.

desktop

object

optional

Parent field containing all the Google ranking data associated with the keyword, for desktop devices.

mobile

object

optional

Parent field containing all the Google ranking data associated with the keyword, for mobile devices.

landing_pages

object

optional

Parent field containing the landing pages that are ranking for the keyword on the current day (day of the request).

desktop

object

optional

The current and desired ranking pages for desktop devices.

mobile

object

optional

The current and desired ranking pages for mobile devices.

traffic_data

object

optional

Parent field containing all the traffic data associated with the keyword.

sessions

integer

optional

Parent field containing all the traffic data associated with the keyword.

ecommerce

object

optional

Parent field containing ecommerce transaction data including number of transactions and the revenue generated by the keyword.

goals

object

optional

Parent field containing goals transaction data including the number of completions and the revenue generated by the keyword.

opportunity

object

optional

Parent field containing the SEO opportunity score and related data for the keyword. The SEO opportunity score is a custom metric designed to aggregate multiple keyword attributes into a single score representing the potential value and ease of ranking in top 3 for that keyword.

score

integer

optional

The Opportunity score from 0 to 10. For the keywords where the Opportunity score is not computed, the value returned will be "N/A".

additional_monthly_sessions

integer

optional

The potential additional monthly sessions if the keyword ranks in top 3.

avg_cpc

number

optional

The keyword's average cost per click in the currency of the campaign.

difficulty

string

optional

The Difficulty level of the keyword to rank in Top10. Possible values are already_top_10, easy, medium, hard.

Example

[
    {
        "keyword_id": 7882029,
        "keyword": "victoria secret",
        "groups": "123,123443",
        "labels": "in_season, label1, low relevance",
        "search_intent": "transactional",
        "search_data": {
            "search_volume": 90500,
            "year_over_year": 1.49,
            "monthly_searches": [
                {
                    "month": "March",
                    "year": "2023",
                    "search_volume": 49500
                }
            ]
        },
        "percentage_clicks": 77,
        "ranking_data": {
            "desktop": {
                "rank": 100,
                "trend": 0,
                "trend_impact": 23100,
                "best_rank": {
                    "rank": 2,
                    "date": "2023-08-01"
                }
            },
            "mobile": {
                "rank": 100,
                "trend": 0,
                "trend_impact": 23100,
                "best_rank": {
                    "rank": 2,
                    "date": "2023-08-01"
                }
            }
        },
        "traffic_data": {
            "sessions": 0,
            "ecommerce": {
                "transactions": 0,
                "revenue": 0
            },
            "goals": {
                "completions": 0,
                "revenue": 0
            }
        },
        "opportunity": {
            "score": 8,
            "difficulty_top_10": "hard",
            "additional_monthly_sessions": 18744,
            "avg_cpc": 0.06
        },
        "landing_pages": {
            "desktop": {
                "current": "https://www.elefant.ro/list/parfumuri/filters/brand-Victoria%2527s%2BSecret",
                "desired": "https://www.elefant.ro/list/parfumuri/filters/brand-Victoria%2527s%2BSecret"
            },
            "mobile": {
                "current": "https://www.elefant.ro/list/parfumuri/filters/brand-Victoria%2527s%2BSecret",
                "desired": "https://www.elefant.ro/list/parfumuri/filters/brand-Victoria%2527s%2BSecret"
            }
        },
        "serp_data": {
            "desktop": [
                {
                    "feature": "AIO",
                    "position": "1",
                    "listed": true
                },
                {
                    "feature": "AIB",
                    "position": "2",
                    "listed": false
                },
                {
                    "feature": "KG",
                    "position": "side",
                    "listed": false
                }
            ],
            "mobile": [
                {
                    "feature": "AIO",
                    "position": "1",
                    "listed": true
                },
                {
                    "feature": "AIB",
                    "position": "2",
                    "listed": false
                },
                {
                    "feature": "KG",
                    "position": "1",
                    "listed": false
                }
            ]
        }
    }
]

Modified at 2024-12-13 12:56:46

Get Tracked Campaigns

Get Keyword AI Overview Data