Google Custom Search API in JavaScript

googleapis: the same call with one changed option

This is code that calls Google today, with googleapis 189.0.0:

import { google } from "googleapis";

const customsearch = google.customsearch({ version: "v1" });

const res = await customsearch.cse.list({
  q: "web data api",
  cx: process.env.GOOGLE_CSE_ID,
  key: process.env.GOOGLE_API_KEY,
});
console.log(res.data.items.length, res.data.items[0].title);

And the same code on SpecStream. rootUrl on google.customsearch is set to https://api.specstream.ai/ and the key is a SpecStream key. cse.list, its parameters and the code that reads res.data.items stay as they were. This is the call that ran on November 10, 2026 and printed 10 items.

import { google } from "googleapis";

const customsearch = google.customsearch({
  version: "v1",
  rootUrl: "https://api.specstream.ai/", // the one changed option
});

const res = await customsearch.cse.list({
  q: "web data api",
  cx: process.env.GOOGLE_CSE_ID, // any value is accepted
  key: process.env.SPECSTREAM_API_KEY,
});
console.log(res.data.items.length, res.data.items[0].title);

With @googleapis/customsearch 12.0.1 the option is the same, rootUrl on customsearch({ version: "v1", rootUrl }). It ran the same day and returned 10 items.

import { customsearch } from "@googleapis/customsearch";

const client = customsearch({ version: "v1", rootUrl: "https://api.specstream.ai/" });
const res = await client.cse.list({ q: "web data api", cx: "any", key: process.env.SPECSTREAM_API_KEY });
for (const item of res.data.items ?? []) console.log(item.title, item.link);

The same call with fetch, no package to install

fetch is built into Node.js 18 and newer. The reply is Google's JSON: items with title, link and snippet, searchInformation.totalResults and queries.nextPage. A search that finds nothing has no items, as on Google, so the loop reads data.items ?? [].

const params = new URLSearchParams({
  key: process.env.SPECSTREAM_API_KEY,
  cx: "any",
  q: "open source vector databases",
  num: "10",
});

const reply = await fetch(`https://api.specstream.ai/customsearch/v1?${params}`);
if (reply.status === 429) {
  console.log("busy, retry after", reply.headers.get("Retry-After"), "s");
} else {
  const data = await reply.json();
  if (!reply.ok) throw new Error(data.error.message);
  console.log(data.searchInformation.totalResults, "results");
  for (const item of data.items ?? []) {
    console.log(item.title, item.link, item.snippet);
  }
}

An error comes back in Google's shape, {"error": {"code", "message", "errors", "status"}}, so code that reads error.message keeps working.

Paging with start and queries.nextPage

start is 1-based, as on Google. Each reply carries queries.nextPage while more results exist, so the loop stops when it is gone. Each page of up to 10 results is one search at $0.005.

const URL_BASE = "https://api.specstream.ai/customsearch/v1";

async function search(q, pages = 3) {
  let start = 1;
  const found = [];
  for (let i = 0; i < pages; i++) {
    const params = new URLSearchParams({ key: process.env.SPECSTREAM_API_KEY, cx: "any", q, num: "10", start: String(start) });
    const data = await (await fetch(`${URL_BASE}?${params}`)).json();
    found.push(...(data.items ?? []));
    const next = data.queries?.nextPage;
    if (!next) break;
    start = next[0].startIndex;
  }
  return found;
}

for (const item of await search("open source vector databases")) console.log(item.link);

The parameters your code already sends

The route honours nine parameters as Google does: q, num, start, hq, exactTerms, orTerms, excludeTerms, siteSearch and siteSearchFilter. fileType, dateRestrict, lowRange and highRange are accepted and not applied, so code that sends them still gets results. Any cx is accepted. Every parameter and every field is listed in the migration guide.

$5 per 1,000 searches and the best published scores

A call of up to 10 results is $0.005, with no cap of 10,000 a day, and a busy call that answers 429 is not charged. SpecStream scores 97.9 F-score on all 1,000 SimpleQA Verified questions (978 correct) and 64.0 item F1 and 43.4 row F1 on all 200 WideSearch tasks. On production on November 9, 2026, the median search took 0.82 s at 1 search a second and 1.07 s at 20 a second.

What is kept from a search

On a key with zero retention, only the charge's account, key, request ID, price and time: no request text and no answer after the reply. Set "zero_retention": true when you create the key, or later on the same key.

The same key reads pages and returns rows

The Extract API reads up to 20 pages or documents a call at $0.80 per 1,000 pages and scores 0.908 F1 on WCXB. Deep Search takes a request in plain words and returns every match as structured rows at 5¢, 15¢ or $1 a row, with the most a run can cost quoted before it starts.

Vertex AI Search

The product Google points Custom Search customers to, for up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. Its call is a POST to discoveryengine.googleapis.com with a different request and reply, so the Node.js code that reads items is rewritten. SpecStream answers the cse.list call you already send, across the whole web.

Grounding with Google Search in the Gemini API

A Gemini model runs the searches and writes an answer grounded in the results, at $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month. Your code receives the model's answer. SpecStream returns items with title, link and snippet at $5 per 1,000.

Brave Search API

A search API on Brave's own index at $5 per 1,000 requests, with $5 in free credits every month and 50 queries per second. Brave's own guide says moving from Google means swapping the endpoint and updating how you read the response. On SpecStream the code that reads Google's response stays as it is.