Google Search and AI Overview tools for the Vercel AI SDK

Step by step

1. 01Install the package

   crawlerdata-ai-sdk has ai and zod as peer dependencies and no other runtime dependencies. Create an API key in the dashboard and export it as CRAWLERDATA_API_KEY.

   npm install crawlerdata-ai-sdk ai zod
   
   # Create a key at https://app.crawlerdata.com, then:
   export CRAWLERDATA_API_KEY=YOUR_API_KEY

2. 02Add the tool to generateText

   crawlerdataSearch() returns an AI SDK tool. The model decides when to call it, and the tool returns the top results, the AI Overview text with its cited sources when Google shows one, and related questions. crawlerdataTools() adds the other four tools. Options are apiKey, country, language, maxResults and timeoutMs.

   The model id below uses the AI Gateway; any AI SDK model works.

   import { generateText, isStepCount } from 'ai';
   import { crawlerdataSearch, crawlerdataTools } from 'crawlerdata-ai-sdk';
   
   // One tool: Google Search with Google's AI Overview and its sources.
   const { text } = await generateText({
     model: 'openai/gpt-5-mini', // any AI SDK model; this id uses the AI Gateway
     prompt: 'Does Google show an AI Overview for "what is a sitemap"? Which sources does it cite?',
     tools: { crawlerdataSearch: crawlerdataSearch() }, // reads CRAWLERDATA_API_KEY
     stopWhen: isStepCount(3),
   });
   console.log(text);
   
   // All five tools (search, news, images, local, autocomplete), with a default country.
   const result = await generateText({
     model: 'openai/gpt-5-mini',
     prompt: 'What is in the news about Nvidia in the UK today? Give me three headlines with sources.',
     tools: crawlerdataTools({ country: 'gb', maxResults: 5 }),
     stopWhen: isStepCount(4),
   });
   console.log(result.text);

3. 03Check what the model receives

   A tool is an ordinary function, so you can call its execute method directly. This is the quickest way to check your key and to see the exact, trimmed result the model gets, which keeps token use low: at most maxResults rows (default 8) and only the fields a model needs.

   // Call a tool directly, without a model, to check your key and see exactly what the model would receive.
   import { crawlerdataSearch, crawlerdataAutocomplete } from 'crawlerdata-ai-sdk';
   
   const search = crawlerdataSearch({ maxResults: 3 }); // reads CRAWLERDATA_API_KEY
   const out = await search.execute({ query: 'what is a sitemap' }, { toolCallId: 'check', messages: [] });
   
   console.log('AI Overview:', out.ai_overview ? out.ai_overview.text.slice(0, 120) + '...' : 'none for this search');
   console.log('Cited:', out.ai_overview?.sources.map((s) => s.link));
   for (const r of out.organic_results) console.log(r.position, r.title, r.link);
   
   const suggest = crawlerdataAutocomplete({ maxResults: 3 });
   console.log((await suggest.execute({ query: 'running sho' }, { toolCallId: 'check', messages: [] })).suggestions);

If something goes wrong

401 INVALID_API_KEY

The key is missing, mistyped or revoked. Send it as "Authorization: Bearer YOUR_API_KEY" (with the word Bearer and one space) and check the key is active under API Access in the dashboard.

402 INSUFFICIENT_CREDITS

Your balance is too low for the request. Buy a credit pack in the dashboard. Requests that fail for other reasons are not charged, so a 402 never costs credits.

429 RATE_LIMITED

Each API key allows 100 requests per minute and 20 per second. Wait until the time in the X-RateLimit-Reset header (a Unix timestamp) and retry, or spread requests out.

Timeouts on live requests

A live request returns when the result is ready. Search requests usually take a few seconds; a Google Shopping sellers request collects every seller for the product, so allow more time. Set the client timeout to about 200 seconds, or use the fast queue and poll the job.

CrawlerData API key missing

The tool found no key. Set CRAWLERDATA_API_KEY or pass { apiKey } to the tool.

Tool errors during generateText

The tool throws a readable message and the AI SDK hands it to the model as a tool error. Run check.mjs to see the underlying error yourself.

Request and response schemas: OpenAPI 3.1 document. Still stuck? Email contact@crawlerdata.com.

APIs you can call

Solutions built on it

Other integrations