Serper

HOW in lib/serper.py. Cheap, fast Google recall — strong first step before structured extraction/enrichment.

Auth & config

• Search base: https://google.serper.dev · Scrape base: https://scrape.serper.dev · Auth: header X-API-KEY (env SERPER_API_KEY; never hardcode).
• All search endpoints POST {q, gl, hl, num, page, location, tbs, autocorrect}.

Operations

search, news, images, places (local businesses), maps, scholar, reviews, autocomplete, scrape(url). Anything else → generic request().

Handoff

Discovery/recall layer. Use search/places/maps to find companies/people/signals, scrape to pull a page → hand to enrichment (Apollo/Lusha/…) or research. Note: places/maps cover the "Google Maps" use case for local sourcing.

Field notes (production experience)

Field-shape note: these are vendor-native operational notes. The client returns the raw vendor JSON and uses the method names in this file — read field shapes accordingly (no normalized-wrapper / result.data. prefix).

• Pick the endpoint: search for broad web research, newsy/changing facts, finding an entity before enrichment, or collecting candidate URLs to hand to extraction. maps for local business discovery, location-aware lookups, and phone/address/rating/website/CID retrieval.
• Treat Serper as a discovery/recall layer - pass strong hits into structured tools (Firecrawl/Apify/provider enrichment). Expect live-search variability; validate important results via the returned URL.

Callable surface — lib/serper.py

Import: from lib.serper import Serper → instantiate Serper() (reads key from env). Base: https://google.serper.dev. Generic passthrough: request(method, path, *, params, json).

• autocomplete(query: str, **opts) -> dict
• images(query: str, **opts) -> dict
• maps(query: str, **opts) -> dict — POST /maps — Google Maps results.
• news(query: str, **opts) -> dict
• ping() -> dict — Key-verification probe. Serper has no free account endpoint, so this fires the cheapest real query (1 result) to confirm the key authenticates — it spends ~1 Serper credit on whichever account the key belongs to (hyreflow charges 0).
• places(query: str, **opts) -> dict — POST /places — Google Places results (local businesses).
• reviews(query: str, **opts) -> dict
• scholar(query: str, **opts) -> dict
• scrape(url: str, *, include_markdown: bool = True) -> dict — POST scrape.serper.dev — fetch & parse a web page (text/markdown).
• search(query: str, **opts) -> dict — POST /search — Google web search. opts: gl, hl, num, page, location, tbs, autocorrect.