Data & sourcing

Serper

A Google search your agent can actually run.

Serper gives the agent live Google results: web, news, maps and local business listings. It is the fastest way to check a fact, find a company's real domain, or pull local firms in a city before anything expensive runs.

Serper is cheap recall at the front of the pipeline. It narrows things down before a credit-costing tool touches them.

things you can ask for

“What is this company's actual domain?”
“Find electrical contractors in Leeds, then cross-check them against permits in Shovels”
“Any news on this firm this month, and has it posted roles on TheirStack?”
“Check whether this person still works there before I spend a credit on Lusha”

works well with Serper

Shovels
confirm a local trades business is actually working
Lusha
enrich only after the cheap check says the person is current
Exa
when keyword search is too literal for the question
Firecrawl
read the page a search result points at

What your agent reads before it touches Serper

Every tool ships with a written playbook, and the agent loads it before the first call. Auth, rate limits, what each call costs, which actions need your approval, and the mistakes worth avoiding. It is the difference between an agent that knows the tool and one that guesses at it.

Read the Serper docs →

Show the raw playbookwritten for the agent

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
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.