Google Custom Search API in Python

The call with requests

This is the whole program. It reads items[] as Google's reply had them, and treats a missing items as no results, which is how Google answers a search that finds nothing.

import os
import requests

BASE = "https://api.specstream.ai"  # was https://www.googleapis.com
KEY = os.environ["SPECSTREAM_API_KEY"]

reply = requests.get(
    f"{BASE}/customsearch/v1",
    params={"key": KEY, "q": "open source vector databases", "num": 10},
    timeout=30,
)
if reply.status_code != 200:
    raise RuntimeError(reply.json()["error"]["message"])

data = reply.json()
print(data["searchInformation"]["totalResults"], "results")
for item in data.get("items", []):
    print(item["title"], item["link"], item["snippet"], sep="\n  ")

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

The same call with urllib, no package to install

import json
import os
import urllib.parse
import urllib.request

params = urllib.parse.urlencode({
    "key": os.environ["SPECSTREAM_API_KEY"],
    "q": "open source vector databases",
    "num": 10,
})
url = f"https://api.specstream.ai/customsearch/v1?{params}"

with urllib.request.urlopen(url, timeout=30) as response:
    data = json.load(response)

for item in data.get("items", []):
    print(item["title"], item["link"])

Paging with start and queries.nextPage

start is 1-based, as on Google. Each reply carries queries.nextPage[0].startIndex while there are more results, so the loop asks for the next page until it is gone. Each page is one search at $0.005.

import os
import requests

URL = "https://api.specstream.ai/customsearch/v1"
KEY = os.environ["SPECSTREAM_API_KEY"]

def search(q, pages=3):
    start, found = 1, []
    for _ in range(pages):
        data = requests.get(
            URL, params={"key": KEY, "q": q, "num": 10, "start": start}, timeout=30
        ).json()
        found += data.get("items", [])
        next_page = data.get("queries", {}).get("nextPage")
        if not next_page:
            break
        start = next_page[0]["startIndex"]
    return found

for item in search("open source vector databases"):
    print(item["link"])

The parameters your code already sends

q, num and start work as on Google. exactTerms, orTerms, siteSearch and hq shape the search as they do there, and fields cuts the reply to the parts you name. The key also works in the X-Goog-Api-Key header or as a Bearer token. searchType=image is refused with a 400: this route returns web results.

$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 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 fast search took 0.82 s at 1 search a second and 1.07 s at 20 a second.

What is kept from a search

Only the charge's account, key, request ID, price and time, on a key with zero retention: no request text and no answer after the reply. Set "zero_retention": true on the key when you create it, 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 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.

Vertex AI Search

Google's suggestion for searching up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. It takes a POST to discoveryengine.googleapis.com with its own request and reply, so the Python code is rewritten. SpecStream answers the call your code already sends, on the whole web.

Grounding with Google Search in the Gemini API

A Gemini model searches and writes an answer grounded in the results. On Gemini 3 and newer it costs $14 per 1,000 search requests after 5,000 free a month. Your code gets the model's answer. SpecStream returns items[] to your code 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 Python that reads Google's response stays.