gscdump

Direct Google Search Console and Bing Webmaster clients with typed queries and Indexing Evidence.

Install

npm install gscdump

gscdump requires Node 22 or newer. It talks to Google over fetch; it does not require the Google API client packages.

Query Search Analytics

Create a client with an access token, an OAuth-like client, or refresh-token credentials:

import { googleSearchConsole } from 'gscdump'

const client = googleSearchConsole({ accessToken: 'ya29.xxx' })
const sites = await client.sites()

Use fetchOptions for custom headers, request hooks, or retry settings:

const client = googleSearchConsole('ya29.xxx', {
  fetchOptions: {
    headers: new Headers({ 'x-project': 'analytics' }),
    retry: 0,
    timeout: 10_000,
    onRequest({ options }) {
      options.headers.set('x-request-id', crypto.randomUUID())
    },
  },
})

Request hooks run after authentication. The client awaits each hook, including arrays of hooks. If you omit retry settings, requests use three retries and respect Google's Retry-After header.

Use gscdump/query to build a request. client.query() paginates through Google's 25,000-row pages and yields each non-empty batch.

import { googleSearchConsole } from 'gscdump'
import { between, date, daysAgo, gsc, page, query } from 'gscdump/query'

const client = googleSearchConsole('ya29.xxx')
const siteUrl = 'sc-domain:example.com'

const request = gsc
  .select(page, query)
  .where(between(date, daysAgo(30), daysAgo(3)))

for await (const rows of client.query(siteUrl, request)) {
  for (const row of rows)
    console.log(row.page, row.query, row.clicks)
}

If you already have a Search Analytics request body, call the direct operation:

const response = await client.searchAnalytics.query(siteUrl, {
  startDate: '2026-06-01',
  endDate: '2026-06-30',
  dimensions: ['page'],
  rowLimit: 1000,
})

Other Google resources

Use the same client for sitemaps, inspections, and eligible Indexing API notifications:

const sitemapList = await client.sitemaps.list(siteUrl)
const inspection = await client.inspect(siteUrl, 'https://example.com/docs')

await client.indexing.publish(
  'https://example.com/jobs/frontend-engineer',
  'URL_UPDATED',
)

Indexing notifications apply only to eligible job or livestream pages. See URL inspection and indexing.

The package root also exports batch and projection helpers such as fetchSitesWithSitemaps, batchInspectUrlsFlatSettled, inspectUrlFlat, and batchRequestIndexing.

Send IndexNow change notifications

Publish a UTF-8 key file on the exact host you submit. The key file contains your key, with no other content.

import { indexNow } from 'gscdump/indexnow'

const client = indexNow()
const input = {
  host: 'example.com',
  key: 'your-key-12345',
  keyLocation: 'https://example.com/your-key-12345.txt',
}
const verification = await client.verify(input)
if (verification.ok && verification.value._tag === 'verified') {
  const result = await client.submit({
    ...input,
    urls: ['https://example.com/changed-page'],
  })
  console.log(result)
}

The client rejects URLs outside the exact host or key directory before sending. Verification allows HTTPS, disables redirects, and reads at most 1,024 bytes within ten seconds. Inject fetch, clock, or timeoutMs when you need different transport or timing. Expected input failures return Result; infrastructure failures propagate.

Submission Receipts describe delivery. HTTP 200 means accepted; HTTP 202 means key validation remains pending. Neither response proves indexing. The direct client sends one batch of up to 10,000 URLs without retries. Hosted callers use the SDK operations, which cap each batch at 1,000 URLs. See the IndexNow protocol.

Read Bing Indexing Evidence

Use gscdump/bing with an OAuth access token or Bing Webmaster API key. The client returns tagged Result values and never infers an indexed verdict from crawl evidence.

import { bingWebmaster } from 'gscdump/bing'

const client = bingWebmaster({ accessToken: 'access-token' })
// API key alternative: bingWebmaster({ apiKey: 'bing-webmaster-api-key' })
const evidence = await client.getIndexingEvidence(
  'https://example.com/',
  'https://example.com/docs',
)

if (evidence.ok)
  console.log(evidence.value)

const [pages, queries, crawl] = await Promise.all([
  client.getPageStats('https://example.com/'),
  client.getQueryStats('https://example.com/'),
  client.getCrawlStats('https://example.com/'),
])

accessToken also accepts a function returning a string or Promise<string>. The client calls that function before each request, so callers can refresh expiring tokens during long exports. The CLI manages this refresh when you use gscdump bing login --mode local --oauth.

Sitemap XML reading and traversal live in sitemapd. Product feed scoping and exact membership hashing live in gscdump/sitemap-identity. Hosted canonical sitemap membership is available through @gscdump/sdk/v1.

Public subpaths

• gscdump/client: Google client and authentication types
• gscdump/indexing: inspection and indexing helpers
• gscdump/indexnow: key verification and change notifications
• gscdump/errors: typed Google API failures
• gscdump/sites: Site helpers
• gscdump/sitemap-identity: sitemap scope and membership hashing
• gscdump/query: query builder, columns, operators, Pacific date helpers, and logical query plans
• gscdump/query/plan: logical query planning only
• gscdump/bing: Bing Site, URL, traffic, crawl evidence, and sitemap calls
• gscdump/dates: explicit UTC and Pacific Search Console date helpers
• gscdump/contracts: Search Analytics request and response contracts
• gscdump/result: Result helpers
• gscdump/normalize: URL normalization
• gscdump/tenant: site ID encoding and normalization

Hosted gscdump.com clients live in @gscdump/sdk. Storage engines and analyzers live in @gscdump/engine and @gscdump/analysis.

License

MIT