<!-- twin of https://specstream.ai/migrate/google-custom-search -->
# Migrate from Google Custom Search: keep the call, change the address

Compared on Nov 10, 2026. The page: https://specstream.ai/migrate/google-custom-search

Google discontinues the Custom Search JSON API on January 1, 2027, and it is already closed to new customers. This guide maps each parameter and each field of `GET /customsearch/v1` to SpecStream.

The switch is one line: `https://api.specstream.ai` in place of `https://www.googleapis.com`, and a SpecStream key in `key=`. The path, the parameters and Google's JSON stay as they are.

SpecStream scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. A call of up to 10 results costs $0.005, which is $5 per 1,000, with no daily limit.

[Get an API key](https://specstream.ai/signup?src=alternatives-migrate-google-custom-search&utm_source=alternatives-md&utm_campaign=migrate-google-custom-search&returnTo=%2Fworkspace%2Fsearch%3Froute%3Dgoogle) New accounts get $10 of credit, no card. It covers 2,000 searches.

## Custom Search JSON API to SpecStream, parameter by parameter and field by field

| | SpecStream | Google Custom Search JSON API |
|---|---|---|
| Address | `GET https://api.specstream.ai/customsearch/v1` | `GET https://www.googleapis.com/customsearch/v1`. Closed to new customers, and discontinued on January 1, 2027 |
| The key | A SpecStream key in `key=`, in the `X-Goog-Api-Key` header or as a Bearer token | An API key, and a Programmable Search Engine you configured |
| `q` and the query parameters | `q` is searched as written. `exactTerms`, `orTerms`, `siteSearch` and `hq` are added to it as search operators | `q` runs against the Programmable Search Engine you configured, which returns web and image results |
| `cx` | Accepted and not used. The search covers the whole live web, and `siteSearch` keeps it to one site | The ID of the Programmable Search Engine to use for the request |
| `num` | 1 to 10, and 10 when you send none. A value outside that range gets `400` | Integers between 1 and 10, inclusive |
| `start` | From 1. `queries.nextPage[0].startIndex` gives the next page, and a page past the last one gets `400` | Never more than 100 results for a query: `start` plus `num` above 100 returns an error |
| `searchType` | Refused with `400`, because the route returns web results. Send the call without `searchType` | Web and image search results from a Programmable Search Engine |
| The reply | `kind` `customsearch#search`, `url`, `queries` with `request`, `nextPage` and `previousPage`, `context`, and `searchInformation` with `searchTime`, `formattedSearchTime`, `totalResults` and `formattedTotalResults` | Metadata about the search, metadata about the engine, and the results, in JSON that follows the OpenSearch 1.1 Specification |
| Each item | `kind`, `title`, `htmlTitle`, `link`, `displayLink`, `snippet`, `htmlSnippet`, `formattedUrl` and `htmlFormattedUrl`. Not returned: `pagemap`, `cacheId`, `mime`, `fileFormat`, `labels` and `image` | The URL, title and text snippets that describe each result |
| Errors | Google's error body: `error.code`, `message`, `errors[]` and `status`, such as `UNAUTHENTICATED` on `401`. A `429` comes with `Retry-After` and charges nothing | Its terms say you may be charged for each successful request |
| Price per 1,000 searches | $5. A call of up to 10 results is one search at $0.005 | $5 per 1,000 queries after 100 free queries a day, for existing customers |
| Daily limit | None. Calls spend from your balance, inside the spending limit you set on the account or the key | 10,000 queries a day |
| More than 10 results a search | On the same key, `GET /v1/web-search` returns up to 100 results for one search with `num`. `num=100` costs $0.059 | 1 to 10 results a call, and never more than 100 results for a query |

## The Custom Search reference, on SpecStream

### The call, before and after

```
# Before
curl "https://www.googleapis.com/customsearch/v1?key=$GOOGLE_KEY&cx=$CX&q=open+source+vector+databases&num=10"

# After
curl "https://api.specstream.ai/customsearch/v1?key=$SPECSTREAM_KEY&cx=$CX&q=open+source+vector+databases&num=10"
```

The path, the parameters and the parser stay. The address changes, and the key. Your code reads `items[].title`, `link` and `snippet` exactly as it did.

### Every parameter, and what the route does with it

Read and used: `q`, `num` (1 to 10), `start` (from 1), and the parameters a search query can carry: `exactTerms`, `orTerms`, `siteSearch` and `hq`.

Read to shape the reply: `fields`. The reply is cut to your selection, such as `fields=items(title,link)`, and a selection that does not parse gets `400`.

Accepted, repeated in `queries.request` and not used in the search: `cx`, `safe`, `gl`, `hl`, `lr`, `cr`, `sort`, `filter`, `googlehost`, `c2coff`, `rights` and `linkSite`. A client that sends them is never refused.

Refused: `searchType`, with `400` and the message "This route returns web results. Send the request without searchType."

### Every field that comes back

The reply has `kind`, `url.template`, `queries` (`request`, and `nextPage` and `previousPage` when there is one), `context`, `searchInformation` and `items`. Each query object carries `title`, `totalResults`, `searchTerms`, `count`, `startIndex`, `inputEncoding`, `outputEncoding`, `safe` and `cx`. `items` is left out of a reply with no result, as on Google.

Each item has `kind` `customsearch#result`, `title`, `htmlTitle`, `link`, `displayLink`, `snippet`, `htmlSnippet`, `formattedUrl` and `htmlFormattedUrl`, with the query's words in `<b>` in the html fields. The route does not return `pagemap`, `cacheId`, `mime`, `fileFormat`, `labels`, `image`, `spelling` or `promotions`. `context.title` is "SpecStream", and `cx` in `queries` is empty unless the call sends one.

One field is added: `specstream`, on the reply and on each item, with what the Search API returns beyond Google's fields, including the call's `price_usd` and `request_id`. A parser that reads Google's fields never sees it.

### $5 per 1,000 searches, with no daily limit

Google's paid rate is $5 per 1,000 queries and it stops at 10,000 queries a day. SpecStream charges $5 per 1,000 searches of up to 10 results and has no daily limit: 10,000 searches a day cost $50, and search 10,001 is answered like the first. A call stopped by a `429` charges nothing, and an `Idempotency-Key` makes a retried call charge once. Credit you buy never expires.

### The most accurate web search API, in about one second

On SimpleQA Verified the SpecStream Search API scores 97.9 F-score on all 1,000 official questions, 978 of them correct. On WideSearch it scores 64.0 item F1 and 43.4 row F1 on all 200 official tasks. The Extract API scores 0.908 F1 on WCXB. Every score and its method is on the [benchmarks](https://specstream.ai/benchmarks?utm_source=alternatives&utm_campaign=migrate-google-custom-search) page.

A Custom Search call runs the fast search. Measured on production on November 9, 2026, its median was 0.82 s at 1 search a second and 1.07 s at 20 a second, the 95th percentile stayed between 1.09 and 1.73 s, and it answered 718 of 720. It takes up to 8,800 searches a minute on one account. A call for results past the first ten runs the default search, at the same price.

### You decide what is kept, on each key

Create the key with `zero_retention` and a search made with it keeps no request text and no answer after the reply: it is not in the history and its log lines carry neither. `spend_cap_cents` is the most the key can spend.

```
curl -X POST https://api.specstream.ai/v1/account/keys \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "production", "scopes": ["account:read", "finds:spend"], "spend_cap_cents": 500000, "zero_retention": true}'
```

### Search, pages and rows on one key

The same key reads up to 20 pages or documents a call with the [Extract API](https://specstream.ai/extract-api?utm_source=alternatives&utm_campaign=migrate-google-custom-search) at $0.80 per 1,000 pages, and a page with no text is not charged. [Deep Search](https://specstream.ai/deep-search?utm_source=alternatives&utm_campaign=migrate-google-custom-search) returns every match for a request in plain words as structured rows, at 5¢, 15¢ or $1 a row, with a source URL on every value. The most a run can cost is approved before it starts. The reasons to move, without the reference, are on the [Custom Search alternative](https://specstream.ai/google-custom-search-api-alternative?utm_source=alternatives&utm_campaign=migrate-google-custom-search) page.

## What else Google offers Custom Search customers

### Vertex AI Search (Agent Search)

Google's named alternative, for searching up to 50 domains. Search Standard Edition costs $1.50 per 1,000 queries and Enterprise Edition $4.00 per 1,000, on a different API: `POST` to `discoveryengine.googleapis.com` with a serving config. SpecStream searches the whole live web on the path your code already calls, in the JSON it already reads.

### Grounding with Google Search in the Gemini API

Gemini 3 and newer models bill each search query the model runs, at $14 per 1,000 search requests after 5,000 free a month. The API returns a grounded answer and search suggestions, not your list of results. SpecStream returns the results your code reads, 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. Its guide says moving from Google means swapping the endpoint and updating how you read the response. On SpecStream the reply is Google's JSON, so there is nothing to update.

### Parallel

A Search API that starts at $1 per 1,000 requests, with 600 Search calls a minute on the Developer plan, in Parallel's own request and reply shape. SpecStream answers Google's call as it is, and takes up to 8,800 searches a minute on one account.

## How to migrate, step by step

1. Create a key under Agents & API in the workspace. A new account gets $10 of credit, no card, which covers 2,000 searches.

2. Set the base address to `https://api.specstream.ai` where your code has `https://www.googleapis.com` or `https://customsearch.googleapis.com`, and send the SpecStream key in `key=`. In Python:

```
import requests

BASE = "https://api.specstream.ai"  # was https://www.googleapis.com

reply = requests.get(
    f"{BASE}/customsearch/v1",
    params={"key": SPECSTREAM_KEY, "cx": CX, "q": "open source vector databases", "num": 10},
    timeout=30,
)
reply.raise_for_status()
for item in reply.json().get("items", []):
    print(item["title"], item["link"], item["snippet"])
```

3. In JavaScript, with the key in the `X-Goog-Api-Key` header:

```
const params = new URLSearchParams({ q: "open source vector databases", num: "10" });
const res = await fetch(`https://api.specstream.ai/customsearch/v1?${params}`, {
  headers: { "X-Goog-Api-Key": process.env.SPECSTREAM_KEY },
});
const data = await res.json();
for (const item of data.items ?? []) console.log(item.title, item.link);
```

If your code uses Google's own client library, change one line. `google-api-python-client` and `googleapis` for Node both work against `https://api.specstream.ai`: set the address where the client is built, put the SpecStream key where Google's key went, and `cse().list(q=..., cx=...)` stays as it is. Tested on November 10, 2026 with versions 2.201.0 and 189.0.0.

```
# Python: google-api-python-client
from googleapiclient.discovery import build

service = build("customsearch", "v1", developerKey=SPECSTREAM_API_KEY,
                client_options={"api_endpoint": "https://api.specstream.ai"})
reply = service.cse().list(q="open source vector databases", cx="any").execute()

// Node: googleapis
const customsearch = google.customsearch({ version: "v1", auth: SPECSTREAM_API_KEY, rootUrl: "https://api.specstream.ai/" });
const reply = await customsearch.cse.list({ q: "open source vector databases", cx: "any" });
```

4. Remove `searchType` if your code sends it, and keep the rest. To page, send the `startIndex` from `queries.nextPage[0]` as `start`. On a `429`, wait the seconds in `Retry-After` and send the call again; nothing was charged.

5. When your product needs every match in place of a results page, write the request in plain words. SpecStream reads it back as the conditions every row must meet and the facts to bring back, quotes the most it can cost, and delivers the rows after you approve.

## Frequently asked questions

### Is the Custom Search JSON API deprecated?

Yes. Google discontinues it on January 1, 2027, and its overview page says the API is closed to new customers. SpecStream answers the same `GET /customsearch/v1` call at `https://api.specstream.ai` today.

### How do I migrate from the Custom Search JSON API in Python?

Change one line: the base address becomes `https://api.specstream.ai`, and `key=` takes a SpecStream key. `requests.get` on `/customsearch/v1` with `q`, `num` and `start` returns Google's JSON, so the loop over `items` stays as it is.

### Does Google's client library work with SpecStream?

Yes. `google-api-python-client` and `googleapis` for Node work with one changed line. In Python, pass `client_options={"api_endpoint": "https://api.specstream.ai"}` to `build`. In Node, pass `rootUrl: "https://api.specstream.ai/"` to `google.customsearch`. The SpecStream key goes where Google's key went, `cx` is sent as before and is not used, and both `cse.list` and `cse.siterestrict.list` answer. On November 10, 2026, 30 calls in a row through the Python client were all answered, with a median of 0.48 seconds.

### Do I still need a search engine ID (cx)?

No. `cx` is accepted and not used, so a call that sends it works unchanged. SpecStream searches the whole live web, and `siteSearch` keeps a search to one site.

### Which Custom Search fields does SpecStream not return?

Eight: `pagemap`, `cacheId`, `mime`, `fileFormat`, `labels`, `image`, `spelling` and `promotions`. Every item has `title`, `htmlTitle`, `link`, `displayLink`, `snippet`, `htmlSnippet`, `formattedUrl` and `htmlFormattedUrl`, and `searchType` is refused with `400`.

### What is the Custom Search JSON API limit?

10,000 queries a day on Google, with 1 to 10 results a call and never more than 100 results for a query. SpecStream has no daily limit, takes up to 8,800 searches a minute on one account, and returns up to 100 results for one search on `/v1/web-search`.

### How much does the Custom Search JSON API cost after the move?

$5 per 1,000 searches of up to 10 results, the same rate Google charges existing customers, with no daily limit. A call stopped by a `429` is not charged, and the first $10 of credit covers 2,000 searches.

## Sources

SpecStream wrote this page. Each Google figure comes from Google's own pages, and each other provider's figure from that company's own page. The route's behavior is taken from its code.

- [Google Custom Search JSON API overview](https://developers.google.com/custom-search/v1/overview), read Nov 9, 2026
- [Google Custom Search JSON API reference, cse.list](https://developers.google.com/custom-search/v1/reference/rest/v1/cse/list), read Nov 9, 2026
- [Google Custom Search JSON API, using REST](https://developers.google.com/custom-search/v1/using_rest), read Nov 9, 2026
- [Google Custom Search terms of service](https://developers.google.com/custom-search/terms), read Nov 9, 2026
- [Google, updates to our web search products](https://programmablesearchengine.googleblog.com/2026/01/updates-to-our-web-search-products.html), read Nov 9, 2026
- [Google Cloud, Agent Search pricing](https://cloud.google.com/generative-ai-app-builder/pricing), read Nov 9, 2026
- [Google Cloud, search method reference](https://cloud.google.com/generative-ai-app-builder/docs/reference/rest/v1/projects.locations.collections.engines.servingConfigs/search), read Nov 9, 2026
- [Gemini API, grounding with Google Search](https://ai.google.dev/gemini-api/docs/google-search), read Nov 9, 2026
- [Brave Search API](https://brave.com/search/api/), read Nov 9, 2026
- [Brave, alternatives to the Google Search API](https://brave.com/learn/google-api-shutdown/), read Nov 9, 2026
- [Parallel pricing](https://parallel.ai/pricing), read Nov 9, 2026
- [SpecStream benchmarks](https://specstream.ai/benchmarks), read Nov 10, 2026
- [SpecStream pricing](https://specstream.ai/pricing), read Nov 10, 2026
- [SpecStream for agents](https://specstream.ai/agents.md), read Nov 10, 2026