searchapi-onboarding

---
name: searchapi-onboarding
description: |
  Onboard an agent to SearchApi. Use when a coding agent first
  encounters SearchApi, for live SERP work (Google, Bing, Yahoo,
  Yandex, Baidu, Naver, DuckDuckGo), Google verticals (News, Maps,
  Shopping, Scholar, Flights, Hotels, Jobs, Events, Trends, Finance,
  Patents, Books, Local, Place, YouTube), commerce (Amazon, eBay,
  Walmart, BestBuy), travel (Airbnb, TripAdvisor, Zillow),
  competitor ad libraries (Meta, LinkedIn, TikTok), social data
  (Facebook, Instagram, TikTok), app stores (Apple, Google Play), or
  wiring SearchApi into product code. Also triggers on "set up
  SearchApi", "install SearchApi", "how do I use SearchApi", "get a
  SearchApi key", or first-time use of any skill in this plugin.
  Routes the reader to the right path: live tools, MCP, app
  integration, or direct REST.
---

# SearchApi: Agent Onboarding

SearchApi gives agents parsed, structured access to search results across **100+ engines**. Use it for SERP scraping (Google, Bing, Yahoo, Yandex, Baidu, Naver, DuckDuckGo), structured data extraction from Google verticals (Maps, Shopping, News, Images, Videos, Scholar, Patents, Trends, Finance, Jobs, Events, Books, Flights, Hotels), competitor and market intelligence (Meta / LinkedIn / Google / TikTok ad libraries, YouTube transcripts and comments, Amazon / Walmart / eBay / BestBuy, Airbnb, TripAdvisor, Zillow, Facebook / Instagram / TikTok profiles, app stores), and any custom workflow you build in code or a Claude skill.

This skill is the entry point. Read it once, pick a path. You can then either hand off to one of this plugin's narrower skills (full list in the routing table below) **or** use SearchApi directly for any custom task, custom script, or app integration. The skills are optional structure, not a requirement.

## Get an API key

1. Sign up at [searchapi.io](https://www.searchapi.io). The **free tier includes 100 free searches**, no credit card required.
2. Copy your key from the dashboard.
3. Save it as an environment variable so every shell session can see it.

**On macOS / Linux:**

```bash
export SEARCHAPI_API_KEY="your-key-here"
```

That sets the key for your **current terminal only** (close the window and it's gone). To make it permanent, you need to add the same line to your shell's startup file:

- If you use **zsh** (default on macOS): open `~/.zshrc` in a text editor and add `export SEARCHAPI_API_KEY="your-key-here"` at the bottom. Save.
- If you use **bash**: same thing but the file is `~/.bashrc` (Linux) or `~/.bash_profile` (older macOS).
- Not sure which shell you have? Run `echo $SHELL` and it'll print something like `/bin/zsh` or `/bin/bash`.
- After editing, either restart your terminal or run `source ~/.zshrc` (or `source ~/.bashrc`) to load it.

**On Windows:** use WSL (Windows Subsystem for Linux) and follow the Linux steps above, or set the env var via System Properties → Environment Variables.

## Pick your path

SearchApi works three equally-supported ways. **All paths are first-class**, pick whichever fits. You can also use more than one.

- **Path A, API key.** Simplest setup. One env var, works in any shell, every skill works.
- **Path B, MCP integrations.** Native tools in Claude Code, with engine isolation per task.
- **Path C, Raw HTTPS.** For when you're calling SearchApi from your own app code (Python, Node, Go, etc.).

> **Agent instruction, present this as a menu, not prose.** When walking a user through onboarding interactively, do NOT describe the three paths in a paragraph and wait. Use the `AskUserQuestion` tool to present a structured choice with these options:
>
> 1. **API key (Recommended)**, "Simplest: one env var, works everywhere"
> 2. **MCP integration**, "Native Claude Code tools from your SearchApi dashboard"
> 3. **App code (raw HTTPS)**, "I'm integrating SearchApi into my own application"
> 4. **Not sure**, "Help me decide"
>
> If the user picks "Not sure", ask one follow-up (also as a menu): "Will you mostly use SearchApi inside Claude Code conversations, or from your own scripts/app?" Claude Code conversations → Path B, scripts/app → Path A or C. Then proceed to the chosen path's section below. Same rule applies later in Path B: when the user needs to choose between `searchapi-all` and narrower bundles, offer that as a menu too.

### Path A, API key

Single env var. Every skill in this plugin can shell out via:

```bash
export SEARCHAPI_API_KEY="your-key-here"
curl -s "https://www.searchapi.io/api/v1/search?engine=ENGINE&q=QUERY&api_key=$SEARCHAPI_API_KEY" | jq
```

No CLI to install, no SDK to import. `curl` and `jq` ship with macOS and most Linux distros; on Windows use WSL.

#### ✅ Verify Path A works (30 seconds)

Run this exact command in your terminal:

```bash
curl -s "https://www.searchapi.io/api/v1/search?engine=google&q=hello&api_key=$SEARCHAPI_API_KEY" | jq '.search_metadata.status'
```

**What you should see:** the word `"Success"` (with quotes) printed back. That's it, Path A works.

**If you see something else:**

| What you see | What's wrong | Fix |
|---|---|---|
| `"Error"` and a message about invalid key | Key isn't set, or is wrong | Run `echo $SEARCHAPI_API_KEY` to confirm. If blank, re-`export` it |
| `jq: command not found` | jq isn't installed | macOS: `brew install jq` · Linux: `apt install jq` |
| Nothing prints at all | Network problem or key wrong | Try without `\| jq` to see the raw response |
| `429` somewhere in the output | Rate-limited | Wait 60 seconds and retry |

Not comfortable with a terminal? Easier path: open Claude Code in any folder and just paste this:

> "My SearchApi key is `<paste your key>`. Set it as `SEARCHAPI_API_KEY` and run a test `curl` to confirm it works."

Claude will run the test and tell you in plain English whether it worked.

### Path B, MCP integrations

SearchApi's MCP integrations are **engine-scoped**: when you create one in the dashboard, you pick which engines/tools it exposes. You can create up to **10 integrations per account**.

**Skill detection rule (important):** This plugin's skills detect MCP integrations by **prefix**, not exact name. Any integration whose name starts with `searchapi-` will be picked up: `searchapi-all`, `searchapi-seo`, `searchapi-myproject`, `searchapi-staging`, anything. You choose the name. The recipe names in [`BUNDLES.md`](../../BUNDLES.md) are just suggested conventions, not requirements.

You also don't need the skills to use the plugin. The MCP works perfectly well on its own for ad-hoc scraping, custom workflows, app-code integration, or any task you write yourself. The skills are bonus structure, not a requirement.

#### Quick start: one integration that covers everything

If you're setting up for the first time and just want it working:

1. Go to [searchapi.io/mcp_integrations/new](https://www.searchapi.io/mcp_integrations/new).
2. **Name it `searchapi-all`** (or anything else starting with `searchapi-`).
3. Tick **all engines** (or whichever subset you know you'll need).
4. Save and copy the MCP URL.
5. Add to Claude Code:

```bash
claude mcp add searchapi-all "<YOUR_MCP_URL>" --transport http
```

> ⚠️ **You must restart Claude Code before the new tools become available.** MCP servers load their tools at session start, so the integration you just added is registered but its tools aren't live in this running session. Either:
> - Type `/exit` and reopen Claude Code, or
> - Open a fresh terminal and start a new `claude` session.
>
> After restart, run `claude mcp list` to confirm the integration shows as **connected**, then come back and continue.

That's it. Every skill in this plugin will detect `searchapi-all` and use it, and you can call any MCP-exposed engine directly through Claude without going through a skill. Note that AI Overview, PAA expansion, and the full `google` engine are not on MCP and need the API-key path (Path A or C).

> 💡 **Trade-off to know:** with every engine enabled, Claude has a larger tool menu to scan on each request (slightly slower, slightly more likely to pick a non-optimal tool). If that becomes a problem, you can split into smaller per-task bundles (see below). Most users won't hit this.

#### Optional: narrower per-task bundles

If `searchapi-all` feels noisy or you want isolated tool menus per task, there are two sources of smaller bundles:

**1. Official SearchApi templates** (fastest): the dashboard at [searchapi.io/mcp_integrations/new](https://www.searchapi.io/mcp_integrations/new) ships pre-made, one-click templates maintained by SearchApi: Google Travel, Google Maps, Google Shopping, Google Scholar, Case Law, News Search, YouTube, Ads Intelligence, Social Profiles, App Stores, Amazon / Walmart / eBay / BestBuy Shopping, Airbnb, TripAdvisor, Zillow. If a template fits your task, pick it, done in one click.

**2. Plugin recipes (unofficial)** for what the templates don't cover, most importantly `searchapi-seo` (core Google SERP, AI Overviews, AI Mode, rank tracking, nothing official covers these), plus media depth, commerce depth, research, and international engines. Full engine lists in [`BUNDLES.md`](../../BUNDLES.md).

Either way, the add command is the same, and **whatever the bundle is called on the dashboard, give it a local name starting with `searchapi-`** so the plugin's skills detect it:

```bash
claude mcp add searchapi-<your-name> "<YOUR_MCP_URL>" --transport http
```

> ⚠️ **Same restart rule applies.** Restart Claude Code (or `/exit` and reopen) before the new tools are usable.

> **Naming convention:** engine names use **underscores** (matching the API `engine=` parameter). Integration names use hyphens. So you'd tick the `google_maps` engine inside an integration named `searchapi-maps`.

**Custom bundles:** any combo works. Pick the engines you need, name the local registration anything starting with `searchapi-`, and the skills will find it.

#### ✅ Verify Path B works (1 minute)

After the restart, confirm the integration is registered and connected:

```bash
claude mcp list
```

**What you should see:** a line showing the integration name you chose (e.g. `searchapi-all`) connected via `http`. If it shows as disconnected or doesn't appear at all, the URL was wrong or the integration was disabled on the dashboard side. Re-copy the URL from [searchapi.io/mcp_integrations/new](https://www.searchapi.io/mcp_integrations/new) and re-run `claude mcp add`.

Then try it in Claude Code. Open a session and ask:

> "Use my searchapi MCP to search Google for 'hello' and show me the first result."

**What you should see:** Claude picks the `google_search_light` tool from your integration, runs it, returns a result. If Claude says "I don't see that MCP," your integration name probably doesn't start with `searchapi-`. Rename it in the dashboard.

Not comfortable with a terminal? Once the dashboard integration is created and you have the MCP URL, paste this into Claude Code:

> "My SearchApi MCP URL for the SEO bundle is `<paste URL>`. Add it as `searchapi-seo` using `claude mcp add`, then verify it's connected and try a test search."

Claude will run all the steps and report back in plain English.

### Path C, Raw HTTPS (in app code)

Pure REST. Any HTTP client works.

```python
import os, requests
r = requests.get(
    "https://www.searchapi.io/api/v1/search",
    params={"engine": "google", "q": "hello", "api_key": os.environ["SEARCHAPI_API_KEY"]},
)
r.raise_for_status()
data = r.json()
```

For production patterns (caching, retries, pagination, cost control), see [`searchapi-best-practices`](../searchapi-best-practices/SKILL.md).

## Setup gate (every skill checks this)

Every other skill starts with a check that **at least one path is configured**:

```bash
if [ -z "$SEARCHAPI_API_KEY" ] && ! claude mcp list 2>/dev/null | grep -q '^searchapi'; then
  echo "Neither SEARCHAPI_API_KEY nor a searchapi-* MCP integration is configured. See searchapi-onboarding."
  exit 1
fi
```

If a skill halts here, come back to this page and finish either Path A or Path B.

## Routing: pick the right skill for the job

> Skills in this plugin are **optional**. If your task doesn't fit any row below, just call the engines you need directly via Path A, B, or C, the plugin works the same.

| Job | Skill |
|---|---|
| Full SEO audit (indexation, rankings, SERP features, PAA, AIO) | [`seo-audit`](../seo-audit/SKILL.md) |
| Rank tracking across keywords / locales | [`rank-tracking`](../rank-tracking/SKILL.md) |
| Google AI Overview / AI Mode presence + citation tracking | [`ai-overview-tracking`](../ai-overview-tracking/SKILL.md) |
| Competitor ad tracking (Meta, LinkedIn, Google Ads Transparency, TikTok) | [`ads-monitor`](../ads-monitor/SKILL.md) |
| Brand mention tracking in Google News (deduped digest, sentiment, risk flags) | [`brand-monitoring`](../brand-monitoring/SKILL.md) |
| Reference: params, pagination, rate limits, errors, deprecations | [`searchapi-best-practices`](../searchapi-best-practices/SKILL.md) |
| E-commerce price monitoring and competitor price audits across Google Shopping plus optional Amazon/eBay/Walmart/BestBuy | [`ecom-price-monitoring`](../ecom-price-monitoring/SKILL.md) |
| Flight fare tracking and fare-calendar watching via Google Flights | [`flight-price-monitor`](../flight-price-monitor/SKILL.md) |
| Scrape local business leads from Google Maps into a CSV (name, address, phone, website, rating, reviews, category, place_id) | [`local-leads-scraper`](../local-leads-scraper/SKILL.md) |
| Turn one keyword into a publish-ready, SERP/PAA/AI-Overview-backed markdown article | [`seo-content-writer`](../seo-content-writer/SKILL.md) |
| End-to-end trip planning over Google Flights, Airbnb, and TripAdvisor (plans and links, never books) | [`travel-planner`](../travel-planner/SKILL.md) |
| Anything else (one-off SERP, shopping, maps, YouTube, travel, social) | call the engine directly via Path A/B/C, no skill needed |

## What SearchApi is *not*

Be honest with the user about scope:

- **No proxy network.** If they need to route their own HTTP client through residential/datacenter IPs, point them at a proxy provider, not us.
- **No browser automation.** If they need to click, scroll, fill forms, or run JS interactively, point them at Playwright / Puppeteer / a browser-API provider.
- **No arbitrary-URL scraping with CAPTCHA bypass.** SearchApi parses known search engines and platforms. For arbitrary HTML extraction, use a scraping API.

We're the **SERP and search-vertical specialist**, that's the sweet spot. Stay in it.

## Troubleshooting

| Symptom | Fix |
|---|---|
| `"status": "Error"` with `"Invalid API key"` | Re-check `echo $SEARCHAPI_API_KEY`, likely empty or stale. Re-export. |
| `429` or rate-limit messages | You hit the per-minute cap on your plan. Sleep + retry, or upgrade. See [`searchapi-best-practices`](../searchapi-best-practices/SKILL.md). |
| Empty `organic_results` | Query may be filtered for the locale. Try adding `&gl=us&hl=en`. |
| `jq: command not found` | Install: `brew install jq` (macOS) / `apt install jq` (Debian/Ubuntu). |
| Wrong engine parameters | Engine schemas at `https://www.searchapi.io/docs/<engine-name>` (e.g. `/docs/google-maps`, `/docs/google-shopping`), or see [`searchapi-best-practices`](../searchapi-best-practices/SKILL.md). |

## Next step

Pick the skill from the routing table above that matches the job in front of you. Don't re-read this skill, go.