playbooks

home / skills / openclaw / skills / serpapi-search

serpapi-search skill

/skills/ericsantos/serpapi-search

This skill searches Google via SerpAPI for web, news, and local results with country and language targeting.

npx playbooks add skill openclaw/skills --skill serpapi-search

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.8 KB
---
name: serpapi
description: Search Google via SerpAPI (Google Search, Google News, Google Local). Use when you need to search the web, find news articles, or look up local businesses. Supports country/language targeting for region-specific results.
metadata: {"clawdbot":{"emoji":"🔍","requires":{"bins":["curl","python3"],"env":["SERPAPI_API_KEY"]},"primaryEnv":"SERPAPI_API_KEY"}}
---

# SerpAPI Search

Search Google via SerpAPI with country/language targeting.

## Quick start

```bash
# Google Search
{baseDir}/scripts/search.sh "artificial intelligence B2B" --country br --lang pt

# Google News
{baseDir}/scripts/search.sh "inteligĂŞncia artificial" --engine google_news --country br --lang pt

# Google Local
{baseDir}/scripts/search.sh "AI companies" --engine google_local --country us --location "San Francisco, California"
```

## Engines

| Engine | Use case | Key results field |
|--------|----------|-------------------|
| `google` | Web search (default) | `organic_results` |
| `google_news` | News articles | `news_results` |
| `google_local` | Local businesses/places | `local_results` |

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `--engine` | `google`, `google_news`, `google_local` | `google` |
| `--country` | 2-letter country code (`br`, `us`, `de`, etc.) | `us` |
| `--lang` | Language code (`pt`, `en`, `es`, etc.) | `en` |
| `--location` | Location string (e.g. `"São Paulo, Brazil"`) | — |
| `--num` | Number of results | `10` |
| `--json` | Raw JSON output | off |

## API key

Set `SERPAPI_API_KEY` env var, or store it:
```bash
mkdir -p ~/.config/serpapi
echo "your_key_here" > ~/.config/serpapi/api_key
chmod 600 ~/.config/serpapi/api_key
```

## Common country codes

`br` (Brazil), `us` (USA), `pt` (Portugal), `de` (Germany), `fr` (France), `es` (Spain), `gb` (UK), `jp` (Japan), `in` (India).

Overview

This skill lets you search Google via SerpAPI for web results, news articles, or local business listings with country and language targeting. It supports Google Search, Google News, and Google Local engines and returns structured results suitable for programmatic consumption. Use it to retrieve region-specific search results, monitor news, or discover local places.

How this skill works

The skill calls SerpAPI using the chosen engine (google, google_news, google_local) and accepts parameters like country, language, location, and number of results. It returns parsed fields such as organic_results for web search, news_results for news, and local_results for places. An API key is required via the SERPAPI_API_KEY environment variable or stored in a config file.

When to use it

  • Gather web search results for research, SEO, or content sourcing.
  • Monitor breaking news or collect recent articles on a topic.
  • Find local businesses or places in a specific city or region.
  • Collect region- and language-specific search data for analysis.
  • Automate search-driven workflows or data pipelines.

Best practices

  • Set SERPAPI_API_KEY securely in your environment or config file with proper file permissions.
  • Choose the engine that matches your need: google, google_news, or google_local.
  • Specify country and lang to reduce noise and get region-relevant results.
  • Limit the number of results (num) to what you need to avoid extra API calls.
  • Parse engine-specific result fields (organic_results, news_results, local_results).

Example use cases

  • Pull the top 10 organic search results for a keyword in Brazil (country=br, lang=pt).
  • Track news articles about a product launch using google_news with a time window.
  • List AI companies in San Francisco using google_local and location="San Francisco, California".
  • Build a localized SERP dataset for SEO tests across multiple countries.
  • Feed recent headlines into an alerting system or daily briefing.

FAQ

Do I need an API key?

Yes. Set SERPAPI_API_KEY in your environment or store it in ~/.config/serpapi/api_key with restrictive permissions.

Which engine returns local businesses?

Use the google_local engine; results are provided in the local_results field and accept a location string for precise targeting.