Google Custom Search API in Ruby

The search with Net::HTTP

Standard library only: net/http and json. A search with no results has no items key on Google or here, so fetch("items", []) keeps the loop safe.

require "net/http"
require "json"

uri = URI("https://api.specstream.ai/customsearch/v1") # was https://www.googleapis.com
uri.query = URI.encode_www_form(
  key: ENV.fetch("SPECSTREAM_API_KEY"),
  cx: "any",
  q: "open source vector databases",
  num: 10
)

response = Net::HTTP.get_response(uri)
data = JSON.parse(response.body)
raise data.dig("error", "message") unless response.is_a?(Net::HTTPSuccess)

puts "#{data.dig("searchInformation", "totalResults")} results"
data.fetch("items", []).each do |item|
  puts item["title"], "  #{item["link"]}", "  #{item["snippet"]}"
end

An error comes back as Google's error object with code, message, errors and status, so a rescue that reads the message needs no change.

If the code uses google-apis-customsearch_v1

Google's Ruby gem starts from DEFAULT_ENDPOINT_TEMPLATE = "https://customsearch.$UNIVERSE_DOMAIN$/" and exposes the address as a writer on the service, def root_url= url_or_template in google-apis-core. Before and after, the same call with that one option set and the key changed:

require "google/apis/customsearch_v1"

# Before: Google
service = Google::Apis::CustomsearchV1::CustomSearchAPIService.new
service.key = ENV["GOOGLE_API_KEY"]
result = service.list_cses(q: "open source vector databases", cx: cx)

# After: the same call, with root_url set
service = Google::Apis::CustomsearchV1::CustomSearchAPIService.new
service.root_url = "https://api.specstream.ai/"
service.key = ENV["SPECSTREAM_API_KEY"]
result = service.list_cses(q: "open source vector databases", cx: cx)

Tested on November 10, 2026 with google-apis-customsearch_v1 0.25.0: the gem's own list_cses read 10 results from https://api.specstream.ai/.

Paging and the 429 reply

start begins at 1. While more results exist, each reply holds queries.nextPage[0].startIndex. When search is busy the route answers 429 with Retry-After in Google's error form and charges nothing; search sleeps that long and asks again. Each page is one search at $0.005.

require "net/http"
require "json"

def search(q, start)
  uri = URI("https://api.specstream.ai/customsearch/v1")
  uri.query = URI.encode_www_form(key: ENV.fetch("SPECSTREAM_API_KEY"), cx: "any", q: q, num: 10, start: start)
  loop do
    response = Net::HTTP.get_response(uri)
    return JSON.parse(response.body) unless response.code == "429"
    sleep [response["Retry-After"].to_i, 1].max
  end
end

start = 1
3.times do
  data = search("open source vector databases", start)
  data.fetch("items", []).each { |item| puts item["link"] }
  next_page = data.dig("queries", "nextPage", 0)
  break unless next_page
  start = next_page["startIndex"]
end

Parameters the route honours

q, num, start, hq, exactTerms, orTerms, excludeTerms, siteSearch and siteSearchFilter: nine in all. fileType, dateRestrict, lowRange and highRange are accepted and not applied. Any cx is accepted, so the engine ID in your credentials can stay. Each parameter and field is in the migration guide.

$5 per 1,000 and the top scores published

A search of up to 10 results is $0.005, the same $5 per 1,000 as Google, and there is no cap where Google stops at 10,000 queries a day. 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 was 0.82 s at 1 search a second and 1.07 s at 20 a second.

What is kept from a search

A key with zero_retention keeps no query text and no reply once the answer is sent. Only the charge stays: account, key, request ID, price and time. Set it when the key is created or later.

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 plain request 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 named alternative for up to 50 domains, at $1.50 per 1,000 queries on Search Standard Edition. It takes a POST to discoveryengine.googleapis.com with a body and reply of its own, so the Ruby that reads items is rewritten. SpecStream answers the GET your code sends, across the whole web.

Grounding with Google Search in the Gemini API

A Gemini model searches, then writes an answer grounded in the results. On Gemini 3 and newer it costs $14 per 1,000 search requests once 5,000 free a month are used, and Ruby receives the answer. SpecStream hands your code the items list 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. In Brave's words, migrating is mostly swapping the endpoint and updating how you read the response. With SpecStream the Ruby that reads Google's response is unchanged.