مستندات توسعه دهندگان

عبارت های نزدیک صفحه اول

GET/sites/{siteId}/search/near-page-one
Scope
search:read
ابزار MCP
near_page_one

Query + page pairs just off page one (striking distance) Search Console query + page pairs whose average position over the last stored 28-day pair window is from minPosition to maxPosition, with at least minImpressions, most impressions first. extraClicks estimates the extra clicks in 28 days at position 3 (typical click-through 10%). Reads the stored pairs (no new lookups). Parameters also work in snake_case (min_position).

توضیح ها از سند OpenAPI می آیند و انگلیسی اند.

پارامترها

ناممحلتوضیح
siteIdاجباریpathstringWebsite id, from GET /sites.
minPositionquerynumberdefault 8, min 1, max 100Lowest average position kept.
maxPositionquerynumberdefault 20, min 1, max 100Highest average position kept; at least minPosition.
minImpressionsqueryintegerdefault 10, min 0, max 100000000Fewest impressions in the window.
urlquerystringA full page URL (exact) or part of one.
fromquerydate (YYYY-MM-DD)With to: use the last stored window ending inside from..to (default: the latest).
toquerydate (YYYY-MM-DD)Last day of the range to look for a stored window in.
pagequeryintegerdefault 1, min 1Page number, from 1.
perqueryintegerdefault 50, min 1, max 500Rows per page, 1 to 500.

پاسخ

200 · application/json

فیلدتوضیح
windowobject or null · required; The 28-day page × query window read (null: no pairs stored)
window.fromdate (YYYY-MM-DD) · required; First day
window.todate (YYYY-MM-DD) · required; Last day
filtersobject · required; Filters applied
filters.minPositionnumber · required; Lowest average position kept
filters.maxPositionnumber · required; Highest average position kept
filters.minImpressionsinteger · required; Fewest impressions kept
filters.urlstring or null · required; Page filter
totalinteger · required; Rows that match, over all pages
pageinteger · required; This page, from 1
perinteger · required; Rows per page
hasMoretrue or false · required; More rows after this page
rowslist of object · required; Pairs, most impressions first
rows[].querystring · required; Search query
rows[].pagestring · required; Page URL
rows[].clicksinteger · required; Clicks in the window
rows[].impressionsinteger · required; Impressions in the window
rows[].ctrnumber · required; Clicks divided by impressions, a fraction (0.05 = 5%), computed from sums
rows[].positionnumber · required; Average position in Google, weighted by impressions (1 is the top)
rows[].extraClicksinteger · required; Estimated extra clicks in 28 days at position 3
notestring · required; How the list is made
linkstring · required; The Search screen in the app

خطاها

کدمعنی
400Bad request. Codes: bad_minPosition, bad_maxPosition, bad_minImpressions, bad_period, bad_page, bad_per.
401Missing, unknown or revoked key. Codes: missing_key, invalid_key.
403The key lacks the scope, covers another website, or its owner lost access. Codes: missing_scope, other_site, owner_left, no_owner, forbidden.
404Not found. Codes: not_found.
429Too 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/near-page-one"

نمونه پاسخ

{
  "window": {
    "from": "2026-09-04",
    "to": "2026-10-01"
  },
  "filters": {
    "minPosition": 8,
    "maxPosition": 20,
    "minImpressions": 10,
    "url": null
  },
  "total": 86,
  "page": 1,
  "per": 50,
  "hasMore": true,
  "rows": [
    {
      "query": "gravel bike sizing chart",
      "page": "https://acmebikes.com/guides/gravel-bike-size-guide",
      "clicks": 38,
      "impressions": 5120,
      "ctr": 0.0074,
      "position": 11.4,
      "extraClicks": 474
    },
    {
      "query": "carbon road bike for beginners",
      "page": "https://acmebikes.com/bikes/road",
      "clicks": 12,
      "impressions": 1840,
      "ctr": 0.0065,
      "position": 14.2,
      "extraClicks": 172
    }
  ],
  "note": "Search Console query + page pairs whose average position over window … is from minPosition to maxPosition, with at least minImpressions; most impressions first.",
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/search"
}

سرور MCP همین کار را با ابزار near_page_one انجام می دهد.