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

One keyword with its expanded row

GET/sites/{siteId}/keywords/{keywordId}
Scope
search:read
ابزار MCP
keyword

One keyword with its expanded row One keyword (the fields of GET /keywords) with what its expanded row on the Keywords screen shows: the related keywords on the same topic with volumes, who ranks in the last stored Google check (engine, location, device) and why it is an opportunity. Who ranks only reads stored checks of tracked keywords; it never buys a new lookup (track the keyword with POST /keywords/track).

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

پارامترها

ناممحلتوضیح
siteIdاجباریpathstringWebsite id, from GET /sites.
keywordIdاجباریpathstringKeyword id, from GET /keywords or keywordId on a gap row.
relatedqueryintegerdefault 4, min 1, max 20How many related keywords; the screen shows 4.

پاسخ

200 · application/json

فیلدتوضیح
keywordobject · required
keyword.idstring
keyword.keywordstring
keyword.sourcestring
keyword.brandedtrue or false
keyword.clusterstring
keyword.intentstring
keyword.locationCodenumber
keyword.locationstring
keyword.languageCodestring
keyword.devicestring
keyword.volumenumber
keyword.difficultynumber
keyword.cpcnumber
keyword.competitionnumber
keyword.monthlylist of numbers
keyword.dataUpdatedAtstring
keyword.positionnumber
keyword.positionFromstring
keyword.gscPositionnumber
keyword.gscClicksnumber
keyword.gscImpressionsnumber
keyword.gscUrlstring
keyword.trackedtrue or false
keyword.latestPositionnumber
keyword.latestUrlstring
keyword.latestDatestring
keyword.deepPositionnumber
keyword.deepDatestring
keyword.weekAgoPositionnumber
keyword.bestPositionnumber
keyword.featureslist of strings
keyword.opportunitystring
keyword.opportunityScorenumber
keyword.relevancenumber
keyword.relevanceStatusstring
keyword.offTopictrue or false
keyword.topicstring
keyword.relevanceReasonstring
keyword.relevanceIntentstring
keyword.actionobject
keyword.action.idstring
keyword.action.statusstring
keyword.action.linkstring
relatedlist of object · required; Keywords on the same topic, most searched first; off-topic ones left out
related[].idstring · required; Keyword id
related[].keywordstring · required; The search phrase
related[].volumeinteger or null · required; Monthly searches (estimate)
related[].positionnumber or null · required; Our position (as position on a keyword); null: not ranking
whoRanksobject or null · required; The "Who ranks" panel: the last stored Google check of the keyword. null when it has none: only tracked keywords are checked, and reading never buys a new lookup
whoRanks.enginegoogle · required; The search engine
whoRanks.datedate (YYYY-MM-DD) · required; Day of the check
whoRanks.observedAtstring · required; When the check read the results
whoRanks.locationCodeinteger · required; Google location id of the check
whoRanks.locationstring · required; The location by name
whoRanks.languageCodestring · required; Language code
whoRanks.devicemobile | desktop · required; Device of the check
whoRanks.ourPositioninteger · required; Our position in that check; 0 = not in the results it read
whoRanks.ourUrlstring or null · required; Our ranking page in that check
whoRanks.resultslist of object · required; The top results that check read, best first
whoRanks.results[].positioninteger · required; Position
whoRanks.results[].domainstring · required; Domain
whoRanks.results[].urlstring or null · required; The ranking page
whoRanks.results[].ourstrue or false · required; This website
whoRanks.featureslist of string · required; Search result features on the page
whyobject · required
why.opportunitydefend | improve | new | · required; The opportunity label
why.textstring · required; "Why it is an opportunity" from the expanded row, in English
why.relevanceReasonstring or null · required; The relevance review's reason, which the screen shows after the text
why.relatedRankinglist of object · required; Related keywords the website already ranks for, best first (up to 10)
why.relatedRanking[].idstring · required; Keyword id
why.relatedRanking[].keywordstring · required; The search phrase
why.relatedRanking[].volumeinteger or null · required; Monthly searches (estimate)
why.relatedRanking[].positionnumber or null · required; Our position (as position on a keyword); null: not ranking
notestring · required; How to read the numbers
linkaddress (URL) · required; The keyword on the Keywords screen

خطاها

کدمعنی
400Bad request. Codes: bad_related.
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, keyword_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/keywords/KEYWORD_ID"

نمونه پاسخ

{
  "keyword": {
    "id": "2d4f6b8d-0f2b-4d4f-9b6d-0f2b4d6f8b0d",
    "keyword": "gravel bike tires",
    "source": "search_console",
    "branded": false,
    "cluster": "gravel tires",
    "intent": "commercial",
    "locationCode": 2840,
    "location": "United States",
    "languageCode": "en",
    "device": "mobile",
    "volume": 2900,
    "difficulty": 34,
    "cpc": 1.12,
    "competition": 0.81,
    "monthly": [
      2400,
      2400,
      2900,
      2900,
      3600,
      3600,
      3600,
      2900,
      2900,
      2400,
      2400,
      2900
    ],
    "dataUpdatedAt": "2026-10-01T04:12:00.000Z",
    "position": 6,
    "positionFrom": "tracked",
    "gscPosition": 7.4,
    "gscClicks": 118,
    "gscImpressions": 3240,
    "gscUrl": "https://acmebikes.com/tires/gravel/",
    "tracked": true,
    "latestPosition": 6,
    "latestUrl": "https://acmebikes.com/tires/gravel/",
    "latestDate": "2026-10-05",
    "deepPosition": 6,
    "deepDate": "2026-10-05",
    "weekAgoPosition": 8,
    "bestPosition": 5,
    "features": [
      "people_also_ask",
      "images"
    ],
    "opportunity": "improve",
    "opportunityScore": 42.7,
    "relevance": 92,
    "relevanceStatus": "reviewed",
    "offTopic": false,
    "topic": "Tires",
    "relevanceReason": "Acme Bikes sells gravel tires on this page.",
    "relevanceIntent": "commercial",
    "action": {
      "id": "b2e4c6a8-1d3f-4a5b-9c7d-0e2f4a6b8c1d",
      "status": "open",
      "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/actions/b2e4c6a8-1d3f-4a5b-9c7d-0e2f4a6b8c1d"
    }
  },
  "related": [
    {
      "id": "c7a9e1b3-5d7f-4b9c-8e1a-3c5e7a9b1d2f",
      "keyword": "gravel bike tyres",
      "volume": 880,
      "position": null
    },
    {
      "id": "0b2d4f6a-8c0e-4a2c-9e4a-8c0e2a4c6e8a",
      "keyword": "best gravel tires",
      "volume": 720,
      "position": 12
    }
  ],
  "whoRanks": {
    "engine": "google",
    "date": "2026-10-05",
    "observedAt": "2026-10-05T03:10:00.000Z",
    "locationCode": 2840,
    "location": "United States",
    "languageCode": "en",
    "device": "mobile",
    "ourPosition": 6,
    "ourUrl": "https://acmebikes.com/tires/gravel/",
    "results": [
      {
        "position": 1,
        "domain": "bikeworld.example",
        "url": "https://bikeworld.example/gravel-tires/",
        "ours": false
      },
      {
        "position": 6,
        "domain": "acmebikes.com",
        "url": "https://acmebikes.com/tires/gravel/",
        "ours": true
      }
    ],
    "features": [
      "people_also_ask"
    ]
  },
  "why": {
    "opportunity": "improve",
    "text": "You rank on page 1 for this. A better page can climb; each step up roughly doubles the clicks.",
    "relevanceReason": "Acme Bikes sells gravel tires on this page.",
    "relatedRanking": [
      {
        "id": "0b2d4f6a-8c0e-4a2c-9e4a-8c0e2a4c6e8a",
        "keyword": "best gravel tires",
        "volume": 720,
        "position": 12
      }
    ]
  },
  "note": "whoRanks: the last stored Google check; null when the keyword has none.",
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/keywords?open=2d4f6b8d-0f2b-4d4f-9b6d-0f2b4d6f8b0d"
}

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