Google Custom Search API in PHP

The search with PHP's curl extension

One request, Google's JSON back. A search that finds nothing has no items key, on Google and here, so the loop reads $data['items'] ?? [].

<?php
$params = http_build_query([
    'key' => getenv('SPECSTREAM_API_KEY'),
    'cx'  => 'any',
    'q'   => 'open source vector databases',
    'num' => 10,
]);
// was https://www.googleapis.com/customsearch/v1
$ch = curl_init("https://api.specstream.ai/customsearch/v1?$params");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status !== 200) {
    throw new RuntimeException($data['error']['message']);
}

echo $data['searchInformation']['totalResults'], " results\n";
foreach ($data['items'] ?? [] as $item) {
    echo $item['title'], "\n  ", $item['link'], "\n  ", $item['snippet'], "\n";
}

A refused call answers in Google's error object, with code, message, errors and status, so the error branch you already have stays as it is.

Without the curl extension: file_get_contents

ignore_errors lets PHP read the JSON body of a 4xx reply instead of returning false.

<?php
$url = 'https://api.specstream.ai/customsearch/v1?' . http_build_query([
    'key' => getenv('SPECSTREAM_API_KEY'),
    'cx'  => 'any',
    'q'   => 'open source vector databases',
]);
$context = stream_context_create(['http' => ['timeout' => 30, 'ignore_errors' => true]]);
$data = json_decode(file_get_contents($url, false, $context), true);

foreach ($data['items'] ?? [] as $item) {
    echo $item['title'], ' ', $item['link'], "\n";
}

If the code uses google/apiclient

The client's CustomSearchAPI class takes the root address as the second argument of its constructor. Its source documents it as @param string $rootUrl The root URL used for requests to the service., and the constructor sets both rootUrl and rootUrlTemplate from it. Here is the same call before and after, with that one option set and the key swapped.

// Before: Google
$client = new Google\Client();
$client->setDeveloperKey(getenv('GOOGLE_API_KEY'));
$service = new Google\Service\CustomSearchAPI($client);
$results = $service->cse->listCse(['q' => 'open source vector databases', 'cx' => $cx]);

// After: the same call, with the constructor's $rootUrl
$client = new Google\Client();
$client->setDeveloperKey(getenv('SPECSTREAM_API_KEY'));
$service = new Google\Service\CustomSearchAPI($client, 'https://api.specstream.ai/');
$results = $service->cse->listCse(['q' => 'open source vector databases', 'cx' => $cx]);

Tested on November 10, 2026 with google/apiclient 2.20.1: the client's own listCse call read 10 results from https://api.specstream.ai/. Pass the address as the constructor's second argument; setting $service->rootUrl after construction is not enough.

Paging, and a busy call

start counts from 1. While more results exist, the reply carries queries.nextPage[0].startIndex. A busy call answers 429 with Retry-After in Google's error form and costs nothing, so search() waits that many seconds and sends it again. Each page is one search at $0.005.

<?php
function search(string $q, int $start): array
{
    $url = 'https://api.specstream.ai/customsearch/v1?' . http_build_query([
        'key' => getenv('SPECSTREAM_API_KEY'), 'cx' => 'any', 'q' => $q, 'num' => 10, 'start' => $start,
    ]);
    while (true) {
        $retryAfter = 1;
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 30,
            CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$retryAfter) {
                if (stripos($line, 'Retry-After:') === 0) {
                    $retryAfter = (int) trim(substr($line, 12));
                }
                return strlen($line);
            },
        ]);
        $body = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($status !== 429) {
            return json_decode($body, true);
        }
        sleep(max(1, $retryAfter));
    }
}

$start = 1;
for ($page = 0; $page < 3; $page++) {
    $data = search('open source vector databases', $start);
    foreach ($data['items'] ?? [] as $item) {
        echo $item['link'], "\n";
    }
    $next = $data['queries']['nextPage'][0]['startIndex'] ?? null;
    if ($next === null) {
        break;
    }
    $start = $next;
}

The parameters the route honours

Nine parameters shape the search: 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 config can stay. Every parameter and field is in the migration guide.

$5 per 1,000 searches, no daily cap

A call of up to 10 results costs $0.005. Google charges the same $5 per 1,000 and stops at 10,000 queries a day; SpecStream has no daily cap. It 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 a second and 1.07 s at 20 a second.

What a search leaves behind

With zero_retention on the key, a search keeps only the charge: account, key, request ID, price and time. The query text and the reply are not kept after the answer. Set it 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 turns a request in plain words into 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 pick for search over up to 50 domains, from $1.50 per 1,000 queries on Search Standard Edition. It is a POST to discoveryengine.googleapis.com with a different body and reply, so the PHP that reads items is rewritten. SpecStream answers the GET your code sends today, across the whole web.

Grounding with Google Search in the Gemini API

A Gemini model runs the search and writes an answer from it. On Gemini 3 and newer models it costs $14 per 1,000 search requests after 5,000 free a month, and PHP receives the model's text. SpecStream returns the result list itself at $5 per 1,000.

Brave Search API

Brave's own index at $5 per 1,000 requests, with $5 in free credits every month. Brave's guide calls the move swapping the endpoint and updating how you read the response. On SpecStream the PHP that reads Google's response stays as written.