Google Custom Search API in Java

The search with java.net.http.HttpClient

The request uses the JDK's own HttpClient (Java 11 and newer); Jackson parses the reply. When a search finds nothing, Google and SpecStream both leave out items, and path("items") then iterates over nothing.

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class CustomSearch {
    public static void main(String[] args) throws Exception {
        String base = "https://api.specstream.ai"; // was https://www.googleapis.com
        String q = URLEncoder.encode("open source vector databases", StandardCharsets.UTF_8);
        URI uri = URI.create(base + "/customsearch/v1?key=" + System.getenv("SPECSTREAM_API_KEY")
                + "&cx=any&num=10&q=" + q);

        HttpClient http = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder(uri).timeout(Duration.ofSeconds(30)).build();
        HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());

        JsonNode data = new ObjectMapper().readTree(response.body());
        if (response.statusCode() != 200) {
            throw new IllegalStateException(data.path("error").path("message").asText());
        }
        System.out.println(data.path("searchInformation").path("totalResults").asText() + " results");
        for (JsonNode item : data.path("items")) {
            System.out.println(item.path("title").asText());
            System.out.println("  " + item.path("link").asText());
            System.out.println("  " + item.path("snippet").asText());
        }
    }
}

Errors keep Google's object, error.code, error.message, error.errors and error.status, so the exception path in your service reads the same fields.

If the code uses google-api-services-customsearch

Google's generated Java client sets its address on the builder. In its source, CustomSearchAPI.java declares DEFAULT_ROOT_URL = "https://customsearch.googleapis.com/" and the builder overrides public Builder setRootUrl(String rootUrl). The same call before and after, with that one option and the key changed:

// Before: Google
CustomSearchAPI service = new CustomSearchAPI.Builder(
        new NetHttpTransport(), GsonFactory.getDefaultInstance(), null)
    .setApplicationName("search")
    .build();
Search result = service.cse().list()
    .setQ("open source vector databases").setCx(cx)
    .setKey(System.getenv("GOOGLE_API_KEY"))
    .execute();

// After: the same call, with setRootUrl on the builder
CustomSearchAPI service = new CustomSearchAPI.Builder(
        new NetHttpTransport(), GsonFactory.getDefaultInstance(), null)
    .setApplicationName("search")
    .setRootUrl("https://api.specstream.ai/")
    .build();
Search result = service.cse().list()
    .setQ("open source vector databases").setCx(cx)
    .setKey(System.getenv("SPECSTREAM_API_KEY"))
    .execute();

Tested on November 10, 2026 with google-api-services-customsearch v1-rev20240821-2.0.0: the client's own cse().list().execute() read 10 results from https://api.specstream.ai/.

Paging and a busy reply

start is 1-based. Each reply names the next page in queries.nextPage[0].startIndex while there is one. A busy call comes back 429 with a Retry-After header, in Google's error form, and is not charged; search sleeps for that many seconds and sends it again. Every page is one search at $0.005.

static JsonNode search(HttpClient http, String q, int start) throws Exception {
    URI uri = URI.create("https://api.specstream.ai/customsearch/v1?key=" + System.getenv("SPECSTREAM_API_KEY")
            + "&cx=any&num=10&start=" + start + "&q=" + URLEncoder.encode(q, StandardCharsets.UTF_8));
    HttpRequest request = HttpRequest.newBuilder(uri).timeout(Duration.ofSeconds(30)).build();
    while (true) {
        HttpResponse<String> response = http.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 429) {
            return new ObjectMapper().readTree(response.body());
        }
        long wait = response.headers().firstValue("Retry-After").map(Long::parseLong).orElse(1L);
        Thread.sleep(Math.max(1L, wait) * 1000);
    }
}

// three pages, up to 30 results
HttpClient http = HttpClient.newHttpClient();
int start = 1;
for (int page = 0; page < 3; page++) {
    JsonNode data = search(http, "open source vector databases", start);
    for (JsonNode item : data.path("items")) {
        System.out.println(item.path("link").asText());
    }
    JsonNode next = data.path("queries").path("nextPage").path(0);
    if (next.isMissingNode()) {
        break;
    }
    start = next.path("startIndex").asInt();
}

Parameters the route honours

Nine: q, num, start, hq, exactTerms, orTerms, excludeTerms, siteSearch and siteSearchFilter. fileType, dateRestrict, lowRange and highRange are accepted and not applied. Any cx is accepted, so the engine ID in your properties file can stay. The migration guide lists every parameter and field.

Google's rate without the 10,000 a day cap

SpecStream charges $5 per 1,000 searches of up to 10 results, the rate Google charges, and has no daily cap where Google stops at 10,000 queries. Scores: 97.9 F-score on all 1,000 SimpleQA Verified questions (978 correct), 64.0 item F1 and 43.4 row F1 on all 200 WideSearch tasks. Measured on production on November 9, 2026: a median of 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 set, nothing of the search stays after the reply except the charge's account, key, request ID, price and time. Turn it on when you make 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, with 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

Google points Custom Search users here for up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. The call is a POST to discoveryengine.googleapis.com with its own request and reply, so the Java that parses items is rewritten. SpecStream answers the request your code already builds, on the whole web.

Grounding with Google Search in the Gemini API

Gemini searches and writes an answer grounded in what it found, at $14 per 1,000 search requests on Gemini 3 and newer after 5,000 free a month. Your service receives the model's answer. SpecStream returns items to your code at $5 per 1,000.

Brave Search API

Search on Brave's own index for $5 per 1,000 requests, with $5 in free credits every month. Brave's guide says migrating is swapping the endpoint and updating how you read the response. With SpecStream the Java that reads Google's response is kept.