Ruby 调用谷歌搜索 API:net/http 与 json 标准库实战

Ruby 做脚本和小工具依然顺手,而且这篇的客户端只用标准库 ------net/http 加 json,连 gem 都不用装,ruby serp_client.rb 直接跑。适合给运维脚本、Sidekiq 任务或任意老项目里加一个搜索数据源。

客户端代码

ruby 复制代码
# serp_client.rb
require 'net/http'
require 'json'
require 'uri'

class SerpClient
  API_URL = URI('https://api.serpbase.dev/google/search')

  def initialize(api_key)
    @api_key = api_key
  end

  # 信封:status 为 0 表示成功;失败时 error 带原因、credits_charged 为 0(不扣费)
  def search(q, hl: 'en', gl: 'us', page: 1)
    body = { q: q, hl: hl, gl: gl, page: page }.to_json

    http = Net::HTTP.new(API_URL.host, API_URL.port)
    http.use_ssl = true
    http.open_timeout = 10
    http.read_timeout = 30

    resp = http.post(API_URL.path, body,
      'X-API-Key'    => @api_key,
      'Content-Type' => 'application/json')

    data = JSON.parse(resp.body)
    if data['status'] != 0
      raise SerpApiError.new(data['status'], data['error'])
    end
    data
  end

  class SerpApiError < StandardError
    attr_reader :code
    def initialize(code, message)
      @code = code
      super("SERP API error #{code}: #{message}")
    end
  end
end

# 用法
client = SerpClient.new(ENV['SERPBASE_API_KEY'])
data = client.search('mechanical keyboard review')

data['organic'].each do |r|
  puts format('%3d  %s', r['rank'], r['title'])
  puts "     #{r['link']}"
end

信封结构、参数表(q/hl/gl/page/device)与 organic 字段定义以 SerpBase 官方文档 为准;rank 是本页内的 1 起算位次,title 和 link 是每条必有字段,snippet、display_url 等为可选------取值前用 r['snippet'] 拿到的是 nil 也别当异常处理。

错误分诊表

信号 含义 动作
SerpApiError 1001 key 缺失/无效 不重试,查配置
SerpApiError 1020 余额不足 告警,人工充值
SerpApiError 1029 触发限流 指数退避重试,最多 3 次
Net::OpenTimeout / Net::ReadTimeout 连接/读取超时 重试一次,再失败记日志
JSON::ParserError 响应非 JSON 记录原始响应前 200 字符

计费口径:search 端点每次成功请求 1 credit;100 次免费试用够在开发环境把这个类调稳,标准包 $0.50/1k 起。

三个 Ruby 特有的坑

  1. Net::HTTP 要 use_ssl = true :https 地址忘了这行会直接报 use_ssl 错误;URI.parse 不会自动开。把 open/read 超时显式设置,默认值在网络抖动时偏长。
  2. data['status'] 的类型 :JSON 里数字就是 Integer,直接 != 0 判断即可;但如果哪天信封升级成字符串,'0' != 0 会误报------防御性写法是 data['status'].to_i != 0。
  3. 别忘了键是字符串 :JSON.parse 默认返回字符串键的 Hash,data[:organic] 永远是 nil,要写 data['organic'];装 symbolize_names: true 参数也行,但团队统一一种风格更重要。

FAQ

为什么不装 httparty 或 faraday? 一个 POST 接口用不上它们;标准库版零依赖,扔进任何项目都不会引起 gem 冲突。等第二个接口出现再抽公共模块不迟。

怎么翻页? search(q, page: 2),page 从 1 起;organic 为空或与上页重复就停。

PAA、相关搜索怎么拿? 返回里是可选模块:data['people_also_ask']、data['related_searches'],用 data.fetch('related_searches', []) 兜底遍历;字段结构以实际返回和文档为准,先原样存 JSON 再建模。

把 serp_client.rb 放进 lib/,配一行环境变量,Rake 任务和 cron 脚本里就都能拿结构化搜索结果了。

相关推荐
wuyk5551 天前
Spider-第16讲-线程池与竞态问题
大数据·爬虫·python·elasticsearch·搜索引擎
wuyk5555 天前
Spider-第11讲-工程化改造与可维护性
大数据·爬虫·elasticsearch·搜索引擎
wuyk5555 天前
Spider-第12讲-asyncio异步并发爬取
大数据·爬虫·elasticsearch·搜索引擎
dozenyaoyida5 天前
AI与大模型新闻日报 | 2026-11-08
人工智能·搜索引擎·ai·大模型·新闻
喵个咪10 天前
GoWind CMS 拆解:搜索三板斧——高亮、联想、同义词
后端·搜索引擎·go
Elastic 中国社区官方博客10 天前
更少的位数,相同的召回率:DiskBBQ 更保守的自动校准扫描
大数据·运维·开发语言·人工智能·elasticsearch·搜索引擎
翊众建站16 天前
用 JSON-LD 给企业官网做结构化数据:LocalBusiness 与 FAQPage 实践笔记
人工智能·搜索引擎·json
fengye20716116 天前
第三章 编译cpython
大数据·elasticsearch·搜索引擎
Elastic 中国社区官方博客17 天前
AgentHack Shanghai|基于阿里云AI搜索 Elasticsearch x Qoder 构建AI Agent应用
大数据·人工智能·elasticsearch·搜索引擎·阿里云·云计算·全文检索
真上帝的左手17 天前
30. 技术专题-‌应用框架组件-搜索引擎-ES
大数据·分布式·elasticsearch·搜索引擎·中间件