Google Search Console

The /v1/gsc/* routes proxy the Google Search Console API for properties you have connected to RankParse. Every call is a live request to Google for one property, so the data is Google-only and exactly as fresh as Search Console itself. Google only returns finalized data, so the most recent day or two are typically missing.

Before you call

Authentication and cost

• Send your API key in the X-API-Key header, as on every other endpoint. See Authentication.
• The Google connection belongs to your workspace, not to the key. Any key in the workspace uses it.
• All /v1/gsc/* routes cost 0 credits. They are limited only by the shared rate limit of 60 requests per minute per key (see Rate limiting) and by Google's own quotas.
• The query routes (search-analytics, sitemaps, url-inspection) require a team role (owner, admin or member). A client-role member gets 403 capability_missing.
• Responses are returned as plain objects. They are not wrapped in the usual data / credits_used envelope.

GET /v1/gsc/status

Reports whether a Google account is connected. It makes no call to Google and is not rate limited.

{
  "connected": true,
  "google_email": "you@example.com",
  "connected_at": 1756112400000,
  "connections": [
    { "id": "conn_abc123", "label": "you@example.com", "status": "active", "property_count": 4 }
  ]
}

GET /v1/gsc/properties

Lists the Search Console properties visible to your connected Google account or accounts. When several accounts are connected, a property visible to more than one is listed once, at the highest permission level.

curl "https://api.rankparse.com/v1/gsc/properties" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/gsc/properties",
    headers={"X-API-Key": "rp_your_key"},
)
print(res.json()["properties"])

const res = await fetch("https://api.rankparse.com/v1/gsc/properties", {
  headers: { "X-API-Key": "rp_your_key" },
});
const { properties } = await res.json();

{
  "properties": [
    { "siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner" },
    { "siteUrl": "https://example.com/", "permissionLevel": "siteFullUser" }
  ]
}

permissionLevel is Google's value for your access to the property (for example siteOwner, siteFullUser, siteRestrictedUser, siteUnverifiedUser).

GET /v1/gsc/search-analytics

Runs a Search Console performance query: clicks, impressions, click-through rate and average position, grouped by the dimensions you choose.

Parameters

Notes on the parameters:

• RankParse checks only that dates look like YYYY-MM-DD. Google applies its own range rules (for example its limited history window), and a request Google rejects comes back as 502 gsc_api_error carrying Google's message.
• filterPage and filterQuery can be used together. Both must match.
• The order of keys in each row follows the order of dimensions that were accepted.
• minPosition, maxPosition, maxCtr and minImpressions are applied by RankParse after Google responds. When any of them is set, RankParse fetches Google's top 1000 rows (Google orders by clicks, descending), filters them, then trims to rowLimit. A filter can therefore only find rows inside that top 1000. For a large property, narrow the date range or add filterPageContains first.

Example

Queries on positions 8 to 20 over the last month, the "quick win" zone:

curl -G "https://api.rankparse.com/v1/gsc/search-analytics" \
  -H "X-API-Key: rp_your_key" \
  --data-urlencode "site=https://example.com/" \
  --data-urlencode "startDate=2026-09-01" \
  --data-urlencode "endDate=2026-09-30" \
  --data-urlencode "dimensions=query" \
  --data-urlencode "minPosition=8" \
  --data-urlencode "maxPosition=20" \
  --data-urlencode "rowLimit=50"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/gsc/search-analytics",
    headers={"X-API-Key": "rp_your_key"},
    params={
        "site": "https://example.com/",
        "startDate": "2026-09-01",
        "endDate": "2026-09-30",
        "dimensions": "query",
        "minPosition": 8,
        "maxPosition": 20,
        "rowLimit": 50,
    },
)
for row in res.json()["rows"]:
    print(row["keys"][0], row["position"], row["impressions"])

const params = new URLSearchParams({
  site: "https://example.com/",
  startDate: "2026-09-01",
  endDate: "2026-09-30",
  dimensions: "query",
  minPosition: "8",
  maxPosition: "20",
  rowLimit: "50",
});
const res = await fetch(`https://api.rankparse.com/v1/gsc/search-analytics?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
const { rows } = await res.json();

Response

{
  "site": "https://example.com/",
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query"],
  "searchType": "web",
  "rows": [
    {
      "keys": ["buy widgets online"],
      "clicks": 14,
      "impressions": 1320,
      "ctr": 0.0106,
      "position": 9.4
    }
  ],
  "responseAggregationType": "byProperty"
}

Response fields

An empty result is a 200 with "rows": [].

Common recipes

GET /v1/gsc/sitemaps

Lists the sitemaps submitted for a property, with Google's processing status.

curl -G "https://api.rankparse.com/v1/gsc/sitemaps" \
  -H "X-API-Key: rp_your_key" \
  --data-urlencode "site=https://example.com/"

{
  "site": "https://example.com/",
  "sitemaps": [
    {
      "path": "https://example.com/sitemap.xml",
      "lastSubmitted": "2026-08-01T10:12:44.000Z",
      "isPending": false,
      "isSitemapsIndex": false,
      "type": "sitemap",
      "lastDownloaded": "2026-09-28T04:30:12.000Z",
      "warnings": 0,
      "errors": 0,
      "contents": [{ "type": "web", "submitted": 412, "indexed": 398 }]
    }
  ]
}

Each sitemap object is Google's own record. path is always present; the other fields (lastSubmitted, isPending, isSitemapsIndex, type, lastDownloaded, warnings, errors, contents) appear when Google reports them. A property with no submitted sitemaps returns "sitemaps": [].

GET /v1/gsc/url-inspection

Returns Google's index status for one URL, using the Search Console URL Inspection API.

curl -G "https://api.rankparse.com/v1/gsc/url-inspection" \
  -H "X-API-Key: rp_your_key" \
  --data-urlencode "site=https://example.com/" \
  --data-urlencode "url=https://example.com/blog/post"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/gsc/url-inspection",
    headers={"X-API-Key": "rp_your_key"},
    params={"site": "https://example.com/", "url": "https://example.com/blog/post"},
)
status = res.json()["inspectionResult"]["indexStatusResult"]
print(status["verdict"], status["coverageState"])

const params = new URLSearchParams({
  site: "https://example.com/",
  url: "https://example.com/blog/post",
});
const res = await fetch(`https://api.rankparse.com/v1/gsc/url-inspection?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
const { inspectionResult } = await res.json();

{
  "site": "https://example.com/",
  "url": "https://example.com/blog/post",
  "inspectionResult": {
    "inspectionResultLink": "https://search.google.com/search-console/inspect?resource_id=https://example.com/&id=abc",
    "indexStatusResult": {
      "verdict": "PASS",
      "coverageState": "Submitted and indexed",
      "robotsTxtState": "ALLOWED",
      "indexingState": "INDEXING_ALLOWED",
      "lastCrawlTime": "2026-09-27T06:14:00Z",
      "pageFetchState": "SUCCESSFUL",
      "googleCanonical": "https://example.com/blog/post",
      "userCanonical": "https://example.com/blog/post",
      "sitemap": ["https://example.com/sitemap.xml"],
      "crawledAs": "MOBILE"
    },
    "mobileUsabilityResult": { "verdict": "PASS" }
  }
}

The inspectionResult object is Google's. indexStatusResult carries verdict, coverageState, robotsTxtState, indexingState, pageFetchState and, when known, lastCrawlTime, googleCanonical, userCanonical, sitemap, referringUrls and crawledAs. ampResult, mobileUsabilityResult and richResultsResult are present when Google evaluates them for the page. Google applies its own URL Inspection quota per property; exceeding it returns 429 gsc_quota_exceeded.

Errors

All errors use the standard shape { "error", "code", "message" }. See Error codes.

MCP tools

These tools wrap the routes above. They are available on the API-key MCP endpoint (mcp.rankparse.com) only. The secure OAuth connector (connect.rankparse.com) does not include any Search Console tool. All are read-only and cost 0 credits. See MCP Server.

Related