Keyword Reporting

The Keyword API allows you to get info about keyword rankings for your site. There are 3 methods available:

  • Integrated Keyword Performance
  • Keyword Ranking Trend
  • Adding New Keywords

Integrated Keyword Performance

This method is best suited for statistics about keyword rankings for given search engine.

Request

  • URL: https://app.ginzametrics.com/api/v3/keywords/rankings
  • HTTP Method: GET

Required Parameters

  • api_key — your API key
  • site_global_key — global key of the site (see “List Account Sites” to obtain it)
  • search_engine_global_key — the search engine to view (eg “google_us”, ”yahoo_us”,”bing_us”).
  • date_from — the start date of the date range (eg “2013-05-01”)
  • date_to — the end date of the date range (eg “2013-05-18”)

Optional Parameters

  • granularity — ‘daily’, ‘weekly’, or ‘monthly’. Default: ‘daily’.
  • groups — comma-separated list of names of the keyword groups to constrain the search (eg “Group_1,Group_2”)
  • conversion_events — the conversion event ids (obtained from Account Sites method) to constrain the search to (eg 42,84,124).
  • limit — the maximum number of keywords to show. Default: 100.
  • offset — the “offset” when limiting the number of keywords to show. Default: 0 or no offset.
  • sort_col — the data column to sort on. Default: ‘visits’.
  • sort_dir — the direction to sort on. Default: ‘desc’.
  • include_keyword_groups — whether display group names for every keyword returned or not (eg “true”)

Sample Request

curl https://app.ginzametrics.com/api/v3/keywords/rankings \
-d api_key=API_KEY \
-d site_global_key=SITE_GLOBAL_KEY \
-d search_engine_global_key=google_us \
-d date_from=2013-03-01 \
-d date_to=2013-03-15 \
-d include_keyword_groups=true

Response

The response will be a JSON object with a request params (just to confirm) and a list of keywords, each with detailed info about their ranking:

keyword A keyword
rank Keyword’s rank at the end of given date range
rank_change Keyword ranking change during given date range
url The URL of the site’s page from search engine’s result page for this keyword
m_visits Number of visits for this page during given date range
m_conversions Number of conversions for this page during given date range
m_revenue Page revenue during given date range
search_volume Number of visits from search engine result page
webmaster_metrics A hash of values from webmaster metrics:
average_position Average rank during given date range
impressions Number of impressions (views)
clicks Number of clicks
ctr Click-through ratio
groups A list of groups that the keyword belongs to (only when URL param include_keyword_groups set to “true”)

Sample Response

{
    "meta": {
        "site_global_key": "GLOBAL_KEY",
        "account_name": "Ginzamarkets, Inc.",
        "search_engine_global_key": "google_us",
        "date_from": "2014-01-01",
        "date_to": "2014-01-14",
        "groups": null,
        "conversion_events": null,
        "sort_col": "rank",
        "sort_dir": "asc",
        "limit": 100,
        "offset": 0,
        "granularity": "daily"
    },
    "keywords": [
        {
            "keyword": "2012 outlook for seo",
            "rank": 1,
            "rank_change": null,
            "url": "https://www.ginzametrics.com/blog/2012-seo-and-inbound-marketing-outlook/",
            "m_visits": "-",
            "m_conversions": 0,
            "m_revenue": 0,
            "search_volume": "-",
            "webmaster_metrics": {
                "average_position": 1,
                "impressions": 44,
                "clicks": 0,
                "ctr": 0
            },
            "groups": [
                "SEO"
            ]
        },
        {
            "keyword": "37 signals saas pricing model",
            "rank": 1,
            "rank_change": null,
            "url": "https://www.ginzametrics.com/blog/dont-blindly-model-your-saas-pricing-on-37signals/",
            "m_visits": "-",
            "m_conversions": 0,
            "m_revenue": 0,
            "search_volume": "-",
            "webmaster_metrics": {
                "average_position": 1,
                "impressions": 43,
                "clicks": 0,
                "ctr": 0
            },
            "groups": [
                "Blog"
            ]
        },
        {
            "keyword": "api ginzametrics",
            "rank": 1,
            "rank_change": null,
            "url": "https://www.ginzametrics.com/api/",
            "m_visits": "-",
            "m_conversions": 0,
            "m_revenue": 0,
            "search_volume": "-",
            "webmaster_metrics": {
                "average_position": 1,
                "impressions": 303,
                "clicks": 0,
                "ctr": 0
            },
            "groups": [
                "Ginza Branded",
                "API"
            ]
        }
    ],
    "search_engine_global_key": "google_us"
}

Keyword Ranking Trends

This method is for checking how keyword ranking changes over time.

Request

  • URL: https://app.ginzametrics.com/api/v3/keywords/rankings_trend
  • HTTP Method: GET

Required Parameters

  • api_key — your API key
  • site_global_key — global key of the site (see “List Account Sites” to obtain it)
  • search_engine_global_key — the search engine to view (eg “google_us”, ”yahoo_us”,”bing_us”).
  • date_from — the start date of the date range (eg “2013-05-01”)
  • date_to — the end date of the date range (eg “2013-05-18”)

Optional Parameters

  • granularity — ‘daily’, ‘weekly’, or ‘monthly’. Default: ‘daily’.
  • groups — comma-separated list of names of the keyword groups to constrain the search (eg “Branded,SEO”)
  • conversion_events — the conversion event ids (obtained from Account Sites method) to constrain the search to (eg 42,84,124).
  • limit — the maximum number of keywords to show. Default: 100.
  • offset — the “offset” when limiting the number of keywords to show. Default: 0 or no offset.
  • sort_col — the data column to sort on. Default: ‘visits’.
  • sort_dir — the direction to sort on. Default: ‘desc’.
  • aggregation — “keywords” or “groups” Default: “keywords”

Sample Request

curl https://app.ginzametrics.com/api/v3/keywords/rankings_trend \
-d api_key=API_KEY \
-d site_global_key=SITE_GLOBAL_KEY \
-d search_engine_global_key=google_us \
-d date_from=2013-03-01 \
-d date_to=2013-03-15

Response

The response will be a JSON object with some meta information about request and a list of keywords, each with info about their ranking for each of date from the given range:

keyword A keyword
trend A list of keyword rankings, for each date from the given range

Sample Response

{
    "meta": {
        "site_global_key": "GLOBAL_KEY",
        "search_engine_global_key": "google_us",
        "date_from": "2014-01-01",
        "date_to": "2014-01-04",
        "granularity": "daily",
        "aggregation": "keywords",
        "offset": 0,
        "limit": 100,
        "groups": null,
        "conversion_events": null,
        "sort_col": "rank",
        "sort_dir": "asc",
        "dates": [
            "2014-01-01",
            "2014-01-02",
            "2014-01-03",
            "2014-01-04"
        ]
    },
    "keywords": [
        {
            "keyword": "2012 outlook for seo",
            "trend": [
                1,
                1,
                1,
                1
            ]
        },
        {
            "keyword": "market size of seo",
            "trend": [
                1,
                1,
                1,
                1
            ]
        },
        {
            "keyword": "odin sso",
            "trend": [
                1,
                1,
                1,
                1
            ]
        },
        {
            "keyword": "bundler vs rvm",
            "trend": [
                2,
                2,
                3,
                2
            ]
        },
        {
            "keyword": "centralization vs decentralization chart",
            "trend": [
                2,
                2,
                2,
                2
            ]
        },
        {
            "keyword": "deploying rails ec2",
            "trend": [
                2,
                2,
                2,
                2
            ]
        },
        {
            "keyword": "deploying rails on aws",
            "trend": [
                2,
                2,
                2,
                2
            ]
        },
        {
            "keyword": "best saas pricing models",
            "trend": [
                2,
                3,
                3,
                3
            ]
        },
        {
            "keyword": "seo industry size",
            "trend": [
                3,
                4,
                3,
                3
            ]
        },
        {
            "keyword": "seo visibility score definition",
            "trend": [
                3,
                3,
                3,
                3
            ]
        },
        {
            "keyword": "support email tips",
            "trend": [
                3,
                2,
                3,
                3
            ]
        }
    ]
}

Adding New Keywords

As its name suggests, this method allows to add new keywords.

Request

  • URL: https://app.ginzametrics.com/api/v3/keywords/add_keywords
  • HTTP Method: GET

Required Parameters

  • api_key — your API key
  • site_global_key — global key of the site (see “List Account Sites” to obtain it)
  • keywords — comma-separated list of keywords to add (eg “enterprize seo,premium seo”).

Optional Parameters

None.

Sample Request

curl https://app.ginzametrics.com/api/v3/keywords/add_keywords \
-d api_key=API_KEY \
-d site_global_key=SITE_GLOBAL_KEY \
-d keywords=enterprize seo,premium seo

Response

The response will be a JSON object with some meta information about processed request and a list of added keywords.

Sample Response

{
    "meta": {
        "site_global_key": "GLOBAL_KEY",
        "account_name": "Ginzamarkets, Inc."
    },
    "keywords": [
        {
            "keyword_id": 16008110,
            "name": "enterprize seo",
            "groups": []
        },
        {
            "keyword_id": 16008111,
            "name": "premium seo",
            "groups": []
        }
    ]
}