Google Custom Search API in Go

customsearch/v1: the same call with one more option

This is code that calls Google today, with google.golang.org/api/customsearch/v1:

svc, err := customsearch.NewService(ctx,
	option.WithAPIKey(os.Getenv("GOOGLE_API_KEY")),
)
if err != nil {
	log.Fatal(err)
}
res, err := svc.Cse.List().Q("web data api").Cx(os.Getenv("GOOGLE_CSE_ID")).Do()

And the whole program on SpecStream. option.WithEndpoint("https://api.specstream.ai/") is added to customsearch.NewService and option.WithAPIKey takes a SpecStream key. svc.Cse.List().Q(...).Cx(...).Do() and the code that reads res.Items stay as they were. This is the call that ran on November 10, 2026 with v0.311.0 and printed 10 items.

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"google.golang.org/api/customsearch/v1"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	svc, err := customsearch.NewService(ctx,
		option.WithAPIKey(os.Getenv("SPECSTREAM_API_KEY")),
		option.WithEndpoint("https://api.specstream.ai/"), // the one changed option
	)
	if err != nil {
		log.Fatal(err)
	}
	res, err := svc.Cse.List().Q("web data api").Cx(os.Getenv("GOOGLE_CSE_ID")).Do()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(len(res.Items), "items")
	for _, item := range res.Items {
		fmt.Println(item.Title, item.Link)
	}
}

The same call with net/http, no module to add

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 data.Items is an empty slice and the loop runs zero times.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"net/url"
	"os"
)

type reply struct {
	Items []struct {
		Title   string `json:"title"`
		Link    string `json:"link"`
		Snippet string `json:"snippet"`
	} `json:"items"`
	Error *struct {
		Message string `json:"message"`
	} `json:"error"`
}

func main() {
	params := url.Values{}
	params.Set("key", os.Getenv("SPECSTREAM_API_KEY"))
	params.Set("cx", "any")
	params.Set("q", "open source vector databases")
	params.Set("num", "10")

	resp, err := http.Get("https://api.specstream.ai/customsearch/v1?" + params.Encode())
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode == http.StatusTooManyRequests {
		log.Fatalf("busy, retry after %s s", resp.Header.Get("Retry-After"))
	}

	var data reply
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	if data.Error != nil {
		log.Fatal(data.Error.Message)
	}
	for _, item := range data.Items {
		fmt.Println(item.Title, item.Link, item.Snippet)
	}
}

An error comes back in Google's shape, {"error": {"code", "message", "errors", "status"}}, so the client library's *googleapi.Error and code that reads error.message keep 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.

// Page with start: 1, 11, 21. Each page of up to 10 is one search.
for _, start := range []int64{1, 11, 21} {
	res, err := svc.Cse.List().Q("open source vector databases").Cx("any").Num(10).Start(start).Do()
	if err != nil {
		log.Fatal(err)
	}
	for _, item := range res.Items {
		fmt.Println(item.Link)
	}
	if len(res.Queries.NextPage) == 0 {
		break
	}
}

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 Go 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.