ردیف های Search Console
/sites/{siteId}/search/rows- Scope
search:read- ابزار MCP
search_rows
Search Console rows for a date range, by query, page, pair or day One row per query, page, query + page pair, or day. CTR (a fraction) and position are computed from sums over the whole range, never averaged across rows. Keyset pages in a stable order (clicks high first, then the key; dimension=date by date): send nextCursor back as cursor until it is null. format=csv streams every row from the cursor on as a CSV file (limit is ignored). What is stored limits the filters: country and device work on daily totals only (dimension=date without page); image search has daily totals only; query_page returns the top 5,000 page × query pairs of the 28 days before the last sync inside the range (see window). A filter the stored data cannot answer returns 400 not_stored.
توضیح ها از سند OpenAPI می آیند و انگلیسی اند.
پارامترها
| نام | محل | توضیح |
|---|---|---|
siteIdاجباری | path | stringWebsite id, from GET /sites. |
fromاجباری | query | date (YYYY-MM-DD)First day, YYYY-MM-DD. The range can be at most 16 months, the history MonoRanks keeps. |
toاجباری | query | date (YYYY-MM-DD)Last day, YYYY-MM-DD, not in the future. |
dimension | query | querypagequery_pagedatedefault queryWhat one row is. |
country | query | stringpattern ^[A-Za-z]{3}$ISO 3166-1 alpha-3 as Search Console uses it, for example usa. dimension=date only. |
device | query | mobiledesktoptabletdimension=date only. |
search_type | query | webimagedefault webWeb or image search. Image search has daily totals only. |
page | query | stringA full URL matches that page exactly; anything else matches pages whose URL contains it (for example /blog/). Works with dimension=page, query_page and date. |
limit | query | integerdefault 1000, min 1, max 10000Rows per page, 1 to 10,000. Ignored with format=csv. |
cursor | query | stringnextCursor from the previous page, unchanged. |
format | query | jsoncsvdefault jsoncsv streams every row as a CSV file. |
پاسخ
200 · application/json
| فیلد | توضیح |
|---|---|
period | object · required; The range asked for |
period.from | date (YYYY-MM-DD) · required; First day |
period.to | date (YYYY-MM-DD) · required; Last day |
dimension | query | page | query_page | date · required; What one row is |
searchType | web | image · required; Search type |
filters | object · required; The filters applied |
filters.country | string or null · required; Country filter (ISO 3166-1 alpha-3, lower case) |
filters.device | MOBILE | DESKTOP | TABLET | · required; Device filter |
filters.page | string or null · required; Page filter |
rows | list of values · required |
rows[].query | string |
rows[].clicks | number |
rows[].impressions | number |
rows[].ctr | number |
rows[].position | number |
nextCursor | string or null · required; Send back as cursor for the next page; null after the last page |
note | string · required; How the numbers are computed |
خطاها
| کد | معنی |
|---|---|
400 | Bad request. Codes: bad_period, period_too_long, bad_dimension, bad_search_type, bad_device, bad_country, not_stored, bad_limit, bad_cursor. |
401 | Missing, unknown or revoked key. Codes: missing_key, invalid_key. |
403 | The key lacks the scope, covers another website, or its owner lost access. Codes: missing_scope, other_site, owner_left, no_owner, forbidden. |
404 | Not found. Codes: not_found. |
429 | Too many requests this hour for this key. Codes: rate_limited. |
نمونه درخواست
curl \
-H "Authorization: Bearer mr_ws_…" \
"https://app.monoranks.com/api/v1/sites/SITE_ID/search/rows?from=2026-09-01&to=2026-09-28"const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/search/rows?from=2026-09-01&to=2026-09-28", {
headers: { Authorization: "Bearer mr_ws_…" },
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();import requests
res = requests.get(
"https://app.monoranks.com/api/v1/sites/SITE_ID/search/rows?from=2026-09-01&to=2026-09-28",
headers={"Authorization": "Bearer mr_ws_…"},
)
res.raise_for_status()
data = res.json()<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/search/rows?from=2026-09-01&to=2026-09-28");
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…"],
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);import axios from "axios";
const { data } = await axios.get("https://app.monoranks.com/api/v1/sites/SITE_ID/search/rows?from=2026-09-01&to=2026-09-28", { headers: { Authorization: "Bearer mr_ws_…" } });نمونه پاسخ
{
"period": {
"from": "2026-09-01",
"to": "2026-09-30"
},
"dimension": "query",
"searchType": "web",
"filters": {
"country": null,
"device": null,
"page": null
},
"rows": [
{
"query": "acme bikes",
"clicks": 571,
"impressions": 2104,
"ctr": 0.2714,
"position": 1.2
},
{
"query": "best gravel bike under 1500",
"clicks": 221,
"impressions": 8890,
"ctr": 0.0249,
"position": 7.8
}
],
"nextCursor": "eyJjIjoyMjEsImsiOiJiZXN0IGdyYXZlbCBiaWtlIHVuZGVyIDE1MDAifQ",
"note": "CTR and position are computed from sums over the period, never averaged across rows. CTR is a fraction (0.05 = 5%)."
}{
"error": {
"code": "bad_period",
"message": "from and to are required, as YYYY-MM-DD."
}
}{
"error": {
"code": "missing_key",
"message": "Send the key as Authorization: Bearer mr_site_…"
}
}{
"error": {
"code": "missing_scope",
"message": "This key does not have the scope this call needs."
}
}{
"error": {
"code": "not_found",
"message": "Website not found."
}
}{
"error": {
"code": "rate_limited",
"message": "More than 1200 requests this hour for this key."
}
}سرور MCP همین کار را با ابزار search_rows انجام می دهد.