<!-- twin of https://specstream.ai/google-custom-search-api-example -->
# Custom Search API example: curl, Python and fetch that run after 2027

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

Google discontinues the Custom Search JSON API on January 1, 2027, and it is closed to new customers today. The examples below call the same `GET /customsearch/v1` at `https://api.specstream.ai`, which answers before and after that date.

Each example sends `key`, `q` and `num` and reads `items[]`, as Google's documentation does. Only the base address and the key differ from Google's.

SpecStream scores 97.9 F-score on all 1,000 SimpleQA Verified questions, on the [benchmarks](https://specstream.ai/benchmarks?utm_source=alternatives&utm_campaign=google-custom-search-api-example) page. Searches cost $5 per 1,000.

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

## The Custom Search call at SpecStream, at Google and on Vertex AI Search

| | SpecStream | Google Custom Search JSON API | Vertex AI Search |
|---|---|---|---|
| The address | `GET https://api.specstream.ai/customsearch/v1` | `GET https://www.googleapis.com/customsearch/v1` | `POST https://discoveryengine.googleapis.com/v1/{servingConfig}:search` |
| After January 1, 2027 | Answers. Open to new accounts today, with $10 of credit and no card | Discontinued on January 1, 2027, and closed to new customers now | Google's suggestion for up to 50 domains, with a free trial of 10,000 queries per account a month |
| What you send | `key`, `q`, `num` and `start`. `cx` is accepted and not used. `exactTerms`, `orTerms`, `siteSearch` and `hq` shape the search | `q`, an API key and `cx`, the ID of a Programmable Search Engine you configured | A JSON body for a serving config you set up in Google Cloud |
| What comes back | Google's JSON: `kind`, `url`, `queries`, `context`, `searchInformation` and `items[]` | Metadata about the search and the engine, and an `items` array with the URL, title and text snippets of each result | Search Enterprise Edition adds generated answers, at $4.00 per 1,000 queries |
| Price per 1,000 | $5 per 1,000 searches. A call of up to 10 results is $0.005 | $5 per 1,000 queries after 100 free queries a day, up to 10,000 a day, for existing customers | $1.50 per 1,000 queries on Search Standard Edition |
| What it searches | The whole live web, read at the moment of the call | The Programmable Search Engine you configured | Up to 50 domains. For full web search, Google asks you to contact it |
| Results a call | `num` from 1 to 10. Up to 100 in one search on `GET /v1/web-search` | 1 to 10, and never more than 100 for a query | Billed per query: any API call to Enterprise Search counts as one |

## The examples, and why they run on SpecStream

### curl

```
curl -G "https://api.specstream.ai/customsearch/v1" \
  --data-urlencode "key=$SPECSTREAM_API_KEY" \
  --data-urlencode "q=open source vector databases" \
  -d num=10 -d start=1
```

The key also works in the `X-Goog-Api-Key` header or as `Authorization: Bearer`.

### Python with requests

```
import os
import requests

reply = requests.get(
    "https://api.specstream.ai/customsearch/v1",
    params={
        "key": os.environ["SPECSTREAM_API_KEY"],
        "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"])
```

The [Python page](https://specstream.ai/google-custom-search-api-python?utm_source=alternatives&utm_campaign=google-custom-search-api-example) has the `urllib` version and a paging loop.

### JavaScript with fetch

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

const response = await fetch(`https://api.specstream.ai/customsearch/v1?${params}`);
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);

for (const item of data.items ?? []) {
  console.log(item.title, item.link, item.snippet);
}
```

This runs in Node 18 and later, Deno, Bun and edge functions. Keep the key on the server.

### The reply, field by field

The reply has Google's shape. Values here are cut to their type.

```
{
  "kind": "customsearch#search",
  "url": { "type": "application/json", "template": "..." },
  "queries": {
    "request":  [{ "searchTerms": "...", "count": 10, "startIndex": 1, "totalResults": "..." }],
    "nextPage": [{ "startIndex": 11, "count": 10 }]
  },
  "context": { "title": "SpecStream" },
  "searchInformation": {
    "searchTime": 0.0, "formattedSearchTime": "...",
    "totalResults": "...", "formattedTotalResults": "..."
  },
  "items": [{
    "kind": "customsearch#result",
    "title": "...", "htmlTitle": "...",
    "link": "...", "displayLink": "...",
    "snippet": "...", "htmlSnippet": "...",
    "formattedUrl": "...", "htmlFormattedUrl": "..."
  }]
}
```

`queries.previousPage` appears from the second page on. `items` is left out of a reply with no results, as on Google. `pagemap` and `cacheId` are not returned. What SpecStream returns beyond Google's fields is under `specstream`, on the reply and on each item. An error has Google's shape: `{"error": {"code", "message", "errors", "status"}}`.

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

A call of up to 10 results is $0.005, with no daily limit, and a `429` with `Retry-After` charges nothing. 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 call took 0.82 s at 1 search a second and 1.07 s at 20 a second, and 718 of 720 calls were answered.

### What is kept from a search

Nothing, on a key with zero retention: no request text and no answer after the reply. It is one field on the key, `zero_retention`, at the same price.

### The same key reads pages and returns rows

The [Extract API](https://specstream.ai/extract-api?utm_source=alternatives&utm_campaign=google-custom-search-api-example) 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](https://specstream.ai/deep-search?utm_source=alternatives&utm_campaign=google-custom-search-api-example) returns every match for a request in plain words as structured rows at 5¢, 15¢ or $1 a row, and quotes the most a run can cost before it starts.

## Other options after the Custom Search JSON API

### Vertex AI Search

Google's suggestion for searching up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. Its request is a `POST` to `discoveryengine.googleapis.com` with its own body and reply, so these examples are rewritten for it. SpecStream runs them as written, on the whole web.

### Grounding with Google Search in the Gemini API

A Gemini model 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 gets the model's answer. SpecStream returns `items[]` 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 describes the move as swapping the endpoint and updating how you read the response. On SpecStream the code that reads Google's response stays.

## How to run the examples

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. Put the key in the environment as `SPECSTREAM_API_KEY`.

```
export SPECSTREAM_API_KEY="your key"
```

3. Run any example above. In code that calls Google today, change `https://www.googleapis.com` or `https://customsearch.googleapis.com` to `https://api.specstream.ai` and the key. `cx` can stay in the call.

## Frequently asked questions

### What is an example of a Custom Search JSON API call?

`GET /customsearch/v1?key=<key>&q=<query>&num=10` returns JSON with an `items` array. Google closes the API on January 1, 2027, and the same call answers at `https://api.specstream.ai/customsearch/v1` with a SpecStream key.

### Where is the Custom Search JSON API documentation?

Google's reference for `cse.list` is at developers.google.com/custom-search, read for this page on November 9, 2026. The SpecStream route follows it: the parameters, the reply and the error shape are Google's, and the fields it does not return are listed on this page.

### Do I need a search engine ID (cx) for these examples?

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

### How do I get the next page of results?

Send `start` with the value in `queries.nextPage[0].startIndex`: 11 after the first 10. Each page is one search at $0.005.

### Can I call it from the browser?

Call it from your server or an edge function, so the key stays out of the page. The `fetch` example runs in Node 18 and later, Deno and Bun as written.

### How much do the examples cost to run?

$0.005 a call of up to 10 results, so 2,000 calls fit in the $10 of credit a new account gets. Google charges existing customers $5 per 1,000 queries after 100 free a day.

## Sources

SpecStream wrote this page. Each figure about Google comes from Google's own pages, and each other figure from that company's own page.

- [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
- [Programmable Search Engine blog: 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: servingConfigs.search method](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
- [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