RevenueScope: revenue-first analytics for your EC site

Search keyword performance

get_keyword_performance

Read-only

Return Google Search Console query metrics. Pass start_date and end_date together (inclusive JST GSC dates); comparison is the immediately preceding equal-length range. Omitting both uses a rolling now-minus-30-days window. Or pass preset (last_4_weeks, last_12_weeks or year_to_date) for the same periods as the app's period picker: the period ends on the last Saturday that closes a complete week (weeks run Sunday to Saturday, judged in the site time zone), and the comparison is the same number of days directly before it; year_to_date starts on January 1 of the year of that Saturday. preset cannot be combined with start_date or end_date, and period.preset echoes it. Each current and previous window uses a separate dashboard_keywords RPC call, capped at 200 queries by clicks. period and previous_period show the actual JST date ranges; date_basis / timezone identify the GSC calendar. source_windows exposes the exact p_from/p_to timestamps used for both RPC calls, whether the GSC date bounds are inclusive, and any JST date shared by the two windows. The rolling default has one shared boundary date; explicit date ranges have none. band='all' returns up to limit rows (default 100) with clicks, impressions, CTR, average position, top page and estimated revenue (search-organic RPS × Google clicks); query-matched changes and truncated disclose omitted/source-limited rows. A query absent from the previous top 200 may appear new. Explicit dates include both JST GSC dates, while session RPS uses [start, end) and excludes the final microsecond. band='striking' (default limit 10) ranks only candidates among the current top 200, with the search screen's borders (shown rank, the average position rounded to a whole number, from 4 to 20, and at least 10 impressions); it is not the best opportunity across all queries. band='keeping' (default limit 10) returns the search screen's 上位維持 list (shown rank 1 to 3 and at least 10 impressions, most impressions first) and band='declining' (default limit 10) returns its 流入減 list (clicks fell by at least max(3, 20% of the earlier clicks), biggest loss first); both judge only within the current and previous top 200 queries by clicks, and each row has current and previous clicks, impressions and rank (shown_position is the whole-number rank the screen shows), rise (previous shown rank minus current, positive is up) and, for declining, click_loss and click_change_pct. Revenue values (est_revenue_jpy, rps_search_jpy, est_revenue_change, est_incremental_revenue_jpy) are null when revenue_status is 'unconfirmed': null means unverified, not 0 yen. Values may differ from the former keyword_breakdown_aggregate because date boundaries, source limit and returned query set differ. Google-search only; data lags 1-2 days. site_id is optional when OAuth-authenticated (omitting it uses the primary site). When the user names a specific site, such as the sample site, call list_sites first and pass that site_id.

Input Schema

TableJSON Schema

Name	Required	Default
`band`	No	all
`limit`	No
`preset`	No
`site_id`	No
`end_date`	No
`start_date`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`band`	Yes
`rows`	Yes
`basis`	No
`notes`	No
`period`	Yes
`site_id`	Yes
`warning`	No
`criteria`	No
`timezone`	Yes
`truncated`	No
`date_basis`	Yes
`assumptions`	No
`limitations`	No
`band_criteria`	No
`revenue_status`	Yes
`rps_search_jpy`	No
`source_windows`	Yes
`previous_period`	Yes
`revenue_estimate_basis`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedOct 9, 2026

changedInput schema / properties / band / enum

Previous value: -[
-  "all",
-  "striking"
-]New value: +[
+  "all",
+  "striking",
+  "keeping",
+  "declining"
+]

addedInput schema / properties / preset

Added value: +{
+  "enum": [
+    "last_4_weeks",
+    "last_12_weeks",
+    "year_to_date"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / band / enum

Previous value: -[
-  "all",
-  "striking"
-]New value: +[
+  "all",
+  "striking",
+  "keeping",
+  "declining"
+]

addedOutput schema / properties / band_criteria

Added value: +{
+  "additionalProperties": {
+    "type": "number"
+  },
+  "type": "object"
+}

addedOutput schema / properties / notes

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / period / properties / preset

Added value: +{
+  "enum": [
+    "last_4_weeks",
+    "last_12_weeks",
+    "year_to_date"
+  ],
+  "type": "string"
+}

removedOutput schema / properties / previous_period / $ref
```
Removed value: -"#/properties/period"
```
addedOutput schema / properties / previous_period / additionalProperties
```
Added value: +false
```

addedOutput schema / properties / previous_period / properties

Added value: +{
+  "days": {
+    "$ref": "#/properties/period/properties/days"
+  },
+  "end": {
+    "$ref": "#/properties/period/properties/end"
+  },
+  "start": {
+    "$ref": "#/properties/period/properties/start"
+  }
+}

addedOutput schema / properties / previous_period / required
```
Added value: +[
+  "start",
+  "end",
+  "days"
+]
```
addedOutput schema / properties / previous_period / type
```
Added value: +"object"
```

addedOutput schema / properties / revenue_status

Added value: +{
+  "enum": [
+    "confirmed",
+    "unconfirmed"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / rows / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "avg_position": {
-          "type": "number"
-        },
-        "clicks": {
-          "type": "number"
-        },
-        "clicks_change": {
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "ctr": {
-          "type": "number"
-        },
-        "est_revenue_change": {
-          "type": [
-            "number",
-            "null"
-          ]
-        },
-        "est_revenue_jpy": {
-          "type": "number"
-        },
-        "impressions": {
-          "type": "number"
-        },
-        "query": {
-          "type": "string"
-        },
-        "rps_search_jpy": {
-          "type": "number"
-        },
-        "top_page": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "required": [
-        "query",
-        "clicks",
-        "impressions",
-        "ctr",
-        "avg_position",
-        "est_revenue_jpy",
-        "top_page",
-        "rps_search_jpy",
-        "clicks_change",
-        "est_revenue_change"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "avg_position": {
-          "type": "number"
-        },
-        "clicks": {
-          "type": "number"
-        },
-        "ctr": {
-          "type": "number"
-        },
-        "est_incremental_clicks": {
-          "type": "number"
-        },
-        "est_incremental_revenue_jpy": {
-          "type": "number"
-        },
-        "impressions": {
-          "type": "number"
-        },
-        "opportunity_score": {
-          "type": "number"
-        },
-        "query": {
-          "type": "string"
-        },
-        "target_position": {
-          "type": "number"
-        },
-        "top_page": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "required": [
-        "query",
-        "avg_position",
-        "impressions",
-        "clicks",
-        "ctr",
-        "top_page",
-        "target_position",
-        "est_incremental_clicks",
-        "est_incremental_revenue_jpy",
-        "opportunity_score"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "type": "number"
+        },
+        "clicks": {
+          "type": "number"
+        },
+        "clicks_change": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "ctr": {
+          "type": "number"
+        },
+        "est_revenue_change": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "est_revenue_jpy": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "impressions": {
+          "type": "number"
+        },
+        "query": {
+          "type": "string"
+        },
+        "rps_search_jpy": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "top_page": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "clicks",
+        "impressions",
+        "ctr",
+        "avg_position",
+        "est_revenue_jpy",
+        "top_page",
+        "rps_search_jpy",
+        "clicks_change",
+        "est_revenue_change"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "type": "number"
+        },
+        "clicks": {
+          "type": "number"
+        },
+        "ctr": {
+          "type": "number"
+        },
+        "est_incremental_clicks": {
+          "type": "number"
+        },
+        "est_incremental_revenue_jpy": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "impressions": {
+          "type": "number"
+        },
+        "opportunity_score": {
+          "type": "number"
+        },
+        "query": {
+          "type": "string"
+        },
+        "target_position": {
+          "type": "number"
+        },
+        "top_page": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "avg_position",
+        "impressions",
+        "clicks",
+        "ctr",
+        "top_page",
+        "target_position",
+        "est_incremental_clicks",
+        "est_incremental_revenue_jpy",
+        "opportunity_score"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "click_change_pct": {
+          "type": "integer"
+        },
+        "click_loss": {
+          "type": "number"
+        },
+        "clicks": {
+          "type": "number"
+        },
+        "impressions": {
+          "type": "number"
+        },
+        "previous_avg_position": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "previous_clicks": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "previous_impressions": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "previous_shown_position": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "query": {
+          "type": "string"
+        },
+        "rise": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "shown_position": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "top_page": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "clicks",
+        "impressions",
+        "avg_position",
+        "shown_position",
+        "previous_clicks",
+        "previous_impressions",
+        "previous_avg_position",
+        "previous_shown_position",
+        "rise",
+        "top_page",
+        "click_loss",
+        "click_change_pct"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/avg_position"
+        },
+        "clicks": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/clicks"
+        },
+        "impressions": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/impressions"
+        },
+        "previous_avg_position": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/previous_avg_position"
+        },
+        "previous_clicks": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/previous_clicks"
+        },
+        "previous_impressions": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/previous_impressions"
+        },
+        "previous_shown_position": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/previous_shown_position"
+        },
+        "query": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/query"
+        },
+        "rise": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/rise"
+        },
+        "shown_position": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/shown_position"
+        },
+        "top_page": {
+          "$ref": "#/properties/rows/anyOf/2/items/properties/top_page"
+        }
+      },
+      "required": [
+        "query",
+        "clicks",
+        "impressions",
+        "avg_position",
+        "shown_position",
+        "previous_clicks",
+        "previous_impressions",
+        "previous_avg_position",
+        "previous_shown_position",
+        "rise",
+        "top_page"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  }
+]

changedOutput schema / properties / rps_search_jpy / type

Previous value: -"number"New value: +[
+  "number",
+  "null"
+]

changedOutput schema / required

Previous value: -[
-  "site_id",
-  "band",
-  "period",
-  "previous_period",
-  "date_basis",
-  "timezone",
-  "source_windows",
-  "rows"
-]New value: +[
+  "site_id",
+  "band",
+  "revenue_status",
+  "period",
+  "previous_period",
+  "date_basis",
+  "timezone",
+  "source_windows",
+  "rows"
+]

Changed9 schema fields changedSep 28, 2026

addedInput schema / properties / end_date

Added value: +{
+  "$ref": "#/properties/start_date"
+}

removedInput schema / properties / period

Removed value: -{
-  "anyOf": [
-    {
-      "const": "today",
-      "type": "string"
-    },
-    {
-      "const": "7d",
-      "type": "string"
-    },
-    {
-      "const": "30d",
-      "type": "string"
-    },
-    {
-      "const": "90d",
-      "type": "string"
-    },
-    {
-      "maximum": 365,
-      "minimum": 1,
-      "type": "integer"
-    }
-  ],
-  "default": "30d"
-}

addedInput schema / properties / start_date

Added value: +{
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedOutput schema / properties / date_basis

Added value: +{
+  "const": "jst_calendar_date",
+  "type": "string"
+}

addedOutput schema / properties / previous_period

Added value: +{
+  "$ref": "#/properties/period"
+}

addedOutput schema / properties / source_windows

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "current": {
+      "additionalProperties": false,
+      "properties": {
+        "p_from": {
+          "type": "string"
+        },
+        "p_to": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "p_from",
+        "p_to"
+      ],
+      "type": "object"
+    },
+    "gsc_date_bounds": {
+      "const": "inclusive",
+      "type": "string"
+    },
+    "previous": {
+      "$ref": "#/properties/source_windows/properties/current"
+    },
+    "shared_jst_dates": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "current",
+    "previous",
+    "gsc_date_bounds",
+    "shared_jst_dates"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / timezone

Added value: +{
+  "const": "Asia/Tokyo",
+  "type": "string"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "omitted_at_least": {
+          "minimum": 0,
+          "type": "integer"
+        },
+        "shown": {
+          "minimum": 0,
+          "type": "integer"
+        },
+        "source_limited": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "shown",
+        "omitted_at_least",
+        "source_limited"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "site_id",
-  "band",
-  "period",
-  "rows"
-]New value: +[
+  "site_id",
+  "band",
+  "period",
+  "previous_period",
+  "date_basis",
+  "timezone",
+  "source_windows",
+  "rows"
+]

Changed1 schema field changedJun 25, 2026

changedOutput schema / properties / rows / anyOf

Previous value: -[
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "avg_position": {
-          "type": "number"
-        },
-        "clicks": {
-          "type": "number"
-        },
-        "ctr": {
-          "type": "number"
-        },
-        "est_revenue_jpy": {
-          "type": "number"
-        },
-        "impressions": {
-          "type": "number"
-        },
-        "query": {
-          "type": "string"
-        },
-        "rps_search_jpy": {
-          "type": "number"
-        },
-        "top_page": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "required": [
-        "query",
-        "clicks",
-        "impressions",
-        "ctr",
-        "avg_position",
-        "est_revenue_jpy",
-        "top_page",
-        "rps_search_jpy"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "items": {
-      "additionalProperties": false,
-      "properties": {
-        "avg_position": {
-          "type": "number"
-        },
-        "clicks": {
-          "type": "number"
-        },
-        "ctr": {
-          "type": "number"
-        },
-        "est_incremental_clicks": {
-          "type": "number"
-        },
-        "est_incremental_revenue_jpy": {
-          "type": "number"
-        },
-        "impressions": {
-          "type": "number"
-        },
-        "opportunity_score": {
-          "type": "number"
-        },
-        "query": {
-          "type": "string"
-        },
-        "target_position": {
-          "type": "number"
-        },
-        "top_page": {
-          "type": [
-            "string",
-            "null"
-          ]
-        }
-      },
-      "required": [
-        "query",
-        "avg_position",
-        "impressions",
-        "clicks",
-        "ctr",
-        "top_page",
-        "target_position",
-        "est_incremental_clicks",
-        "est_incremental_revenue_jpy",
-        "opportunity_score"
-      ],
-      "type": "object"
-    },
-    "type": "array"
-  }
-]New value: +[
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "type": "number"
+        },
+        "clicks": {
+          "type": "number"
+        },
+        "clicks_change": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "ctr": {
+          "type": "number"
+        },
+        "est_revenue_change": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "est_revenue_jpy": {
+          "type": "number"
+        },
+        "impressions": {
+          "type": "number"
+        },
+        "query": {
+          "type": "string"
+        },
+        "rps_search_jpy": {
+          "type": "number"
+        },
+        "top_page": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "clicks",
+        "impressions",
+        "ctr",
+        "avg_position",
+        "est_revenue_jpy",
+        "top_page",
+        "rps_search_jpy",
+        "clicks_change",
+        "est_revenue_change"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "items": {
+      "additionalProperties": false,
+      "properties": {
+        "avg_position": {
+          "type": "number"
+        },
+        "clicks": {
+          "type": "number"
+        },
+        "ctr": {
+          "type": "number"
+        },
+        "est_incremental_clicks": {
+          "type": "number"
+        },
+        "est_incremental_revenue_jpy": {
+          "type": "number"
+        },
+        "impressions": {
+          "type": "number"
+        },
+        "opportunity_score": {
+          "type": "number"
+        },
+        "query": {
+          "type": "string"
+        },
+        "target_position": {
+          "type": "number"
+        },
+        "top_page": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "query",
+        "avg_position",
+        "impressions",
+        "clicks",
+        "ctr",
+        "top_page",
+        "target_position",
+        "est_incremental_clicks",
+        "est_incremental_revenue_jpy",
+        "opportunity_score"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  }
+]

Changed1 schema field changedJun 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "assumptions": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "band": {
+      "enum": [
+        "all",
+        "striking"
+      ],
+      "type": "string"
+    },
+    "basis": {
+      "type": "string"
+    },
+    "criteria": {
+      "additionalProperties": false,
+      "properties": {
+        "min_impressions": {
+          "type": "number"
+        },
+        "position_max": {
+          "type": "number"
+        },
+        "position_min": {
+          "type": "number"
+        },
+        "target_position": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "position_min",
+        "position_max",
+        "min_impressions",
+        "target_position"
+      ],
+      "type": "object"
+    },
+    "limitations": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "period": {
+      "additionalProperties": false,
+      "properties": {
+        "days": {
+          "type": "number"
+        },
+        "end": {
+          "type": "string"
+        },
+        "start": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "start",
+        "end",
+        "days"
+      ],
+      "type": "object"
+    },
+    "revenue_estimate_basis": {
+      "type": "string"
+    },
+    "rows": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "avg_position": {
+                "type": "number"
+              },
+              "clicks": {
+                "type": "number"
+              },
+              "ctr": {
+                "type": "number"
+              },
+              "est_revenue_jpy": {
+                "type": "number"
+              },
+              "impressions": {
+                "type": "number"
+              },
+              "query": {
+                "type": "string"
+              },
+              "rps_search_jpy": {
+                "type": "number"
+              },
+              "top_page": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "query",
+              "clicks",
+              "impressions",
+              "ctr",
+              "avg_position",
+              "est_revenue_jpy",
+              "top_page",
+              "rps_search_jpy"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "avg_position": {
+                "type": "number"
+              },
+              "clicks": {
+                "type": "number"
+              },
+              "ctr": {
+                "type": "number"
+              },
+              "est_incremental_clicks": {
+                "type": "number"
+              },
+              "est_incremental_revenue_jpy": {
+                "type": "number"
+              },
+              "impressions": {
+                "type": "number"
+              },
+              "opportunity_score": {
+                "type": "number"
+              },
+              "query": {
+                "type": "string"
+              },
+              "target_position": {
+                "type": "number"
+              },
+              "top_page": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "query",
+              "avg_position",
+              "impressions",
+              "clicks",
+              "ctr",
+              "top_page",
+              "target_position",
+              "est_incremental_clicks",
+              "est_incremental_revenue_jpy",
+              "opportunity_score"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        }
+      ]
+    },
+    "rps_search_jpy": {
+      "type": "number"
+    },
+    "site_id": {
+      "type": "string"
+    },
+    "warning": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "site_id",
+    "band",
+    "period",
+    "rows"
+  ],
+  "type": "object"
+}

AddedJun 3, 2026

TDQS

Score is being calculated.

All RevenueScope: revenue-first analytics for your EC site tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?