Master reference for SearchApi.io, the comprehensive guide an agent consults whenever it needs depth on any SearchApi capability that another skill didn't already cover. Covers authentication (API key, MCP, Bearer header), every engine family with key params and gotchas, locale handling, pagination patterns, rate limits, retry/backoff, error codes, cost optimization, deprecation log, and the four utility/account APIs (`/me`, `/locations`, `/search_history`, `/search_analytics`). Use when: imp...
Scanned 8/6/2026
Install via CLI
Skills Directoryopenskills install SamJale/SearchApi-Claude-Plugin---
name: searchapi-best-practices
description: |
Master reference for SearchApi.io, the comprehensive guide an agent
consults whenever it needs depth on any SearchApi capability that
another skill didn't already cover. Covers authentication (API key,
MCP, Bearer header), every engine family with key params and
gotchas, locale handling, pagination patterns, rate limits,
retry/backoff, error codes, cost optimization, deprecation log, and
the four utility/account APIs (`/me`, `/locations`,
`/search_history`, `/search_analytics`). Use when: implementing
SearchApi in app code; looking up engine-specific parameters or
response shapes; debugging an unexpected response; choosing between
similar engines (e.g. `google` vs `google_light`); planning token-driven workflows (Shopping pipeline, Maps pipeline, Trends → News,
Ad library tiers); auditing cost; or answering "what does
SearchApi do?" at depth. This is the encyclopedia. Other skills are
the recipes.
---
# SearchApi Master Reference (Best Practices)
The depth other skills hand off to for engine calls and response shapes. Other skills in this plugin handle specific jobs (SEO audits, rank tracking, ads research).
**This skill is a condensed guide, not the canonical record.** Each topic has one authoritative file, listed in the [document map](../../CONVENTIONS.md#document-map-which-file-owns-what). For engine params and response shapes that is [`ENGINES-REFERENCE.md`](../../ENGINES-REFERENCE.md); where the two disagree, it wins.
> **REST vs MCP:** this reference describes the **REST API**. MCP tools are defined separately: the catalog is a strict subset, tool names often differ from engine names, one engine can back several tools, and many engines have no MCP tool at all. Never infer MCP availability from an engine's presence here — check [`MCP-TOOLS.md`](../../MCP-TOOLS.md), which owns that mapping and the REST-only list.
---
## What SearchApi is (and isn't)
**SearchApi is the SERP & search-vertical specialist.** Parsed, structured access to **100+ endpoints** across Google (Search, News, Maps, Shopping, Flights, Hotels, Travel Explore, Scholar, Patents, Books, Finance, Jobs, Events, Trends, Lens, Autocomplete, AI Overview, AI Mode, About-This-Domain, Related Questions, Rank Tracking, Ads Transparency, Play Store), Bing (+ News, Images, Videos, Shopping), Yahoo, Yandex (+ Reverse Image), Baidu, Naver, DuckDuckGo (+ light/images/videos), YouTube (6 engines), Amazon / Walmart / eBay / BestBuy, Airbnb / TripAdvisor / Zillow, Apple App Store + Google Play, Facebook / Instagram / TikTok profiles, and Meta / LinkedIn / Google / TikTok ad libraries.
**Use SearchApi when** you want clean parsed JSON from search engines or known platforms.
**Use something else when:**
- You need a **proxy network** to route your own HTTP clients (try a proxy provider)
- You need **full browser automation** to click, scroll, fill forms (use Playwright / Puppeteer / a browser API)
- You need **arbitrary URL scraping** with JS rendering + CAPTCHA bypass (use a scraping API; SearchApi parses known platforms only)
---
## Authentication
Two equivalent ways to pass the key. Pick one per request, don't mix.
### Query parameter (simplest)
```bash
curl -s "https://www.searchapi.io/api/v1/search?engine=google&q=hello&api_key=$SEARCHAPI_API_KEY"
```
### Bearer header (preferred when the URL would otherwise leak the key)
```bash
curl -s -H "Authorization: Bearer $SEARCHAPI_API_KEY" \
"https://www.searchapi.io/api/v1/search?engine=google&q=hello"
```
Use the header form in shared logs, CI, or any environment where a URL might be captured.
### MCP path
If the user has configured an MCP integration (see [`BUNDLES.md`](../../BUNDLES.md)), authentication is handled by the dashboard-issued MCP URL. No need to pass `api_key` per call. Claude calls the tool, MCP handles auth. For which tool maps to which engine, see [`MCP-TOOLS.md`](../../MCP-TOOLS.md).
---
## The base endpoint
Every search engine uses one unified URL:
```
GET https://www.searchapi.io/api/v1/search
?engine=<engine_name> # API uses underscores
&api_key=<key> # or use Authorization: Bearer header
&q=<query> # required for most engines
& ...engine-specific params
```
> **Naming convention:** API `engine=` values use **underscores** (`google_maps`). Docs URL slugs use **hyphens** (`searchapi.io/docs/google-maps`). Don't mix.
---
## Universal parameters
These work across most engines:
| Param | Type | Purpose |
|---|---|---|
| `api_key` | string | Auth (or use Bearer header) |
| `q` | string | The search query (required for search engines) |
| `gl` | 2-letter code | Country (`us`, `uk`, `de`, …) |
| `hl` | 2-letter code | UI / interface language |
| `location` | string | Place name (e.g. `Brooklyn,New York,United States`), mutually exclusive with `uule`. |
| `uule` | encoded string | Google location encoding, mutually exclusive with `location`. |
| `device` | `desktop` / `mobile` / `tablet` | Render context (affects mobile-only blocks) |
| `page` | integer (1-indexed) | Pagination |
| `safe` | `active` / `blur` / `off` | Safe search |
| `time_period` | enum | Time filter (`last_day`/`last_week`/`last_month`/…) |
| `zero_retention` | bool | Enterprise-only, disables logging |
### Deprecated, don't use
- `google_domain` and ccTLDs, **deprecated April 15 2025**, use `gl`/`hl`
- `num`, **fixed at 10/page for Google since Sept 2025**, no longer adjustable
---
## Universal response shape
All engines return:
```json
{
"search_metadata": {
"id": "...",
"status": "Success", // or "Error"
"created_at": "...",
"request_time_taken": 1.23,
"parsing_time_taken": 0.05,
"total_time_taken": 1.28,
"request_url": "..."
},
"search_parameters": { /* echo of params */ },
"search_information": { "query_displayed": "...", "total_results": ... },
// engine-specific top-level keys: organic_results, local_results, ai_overview, etc.
"pagination": { "current": 1, "next": "...", "next_page_token": "..." }
}
```
> **Engine-specific keys:** `next_page_token` and `search_information.total_results` are NOT universal, they're engine-specific. For example `google_light` omits both and returns only `pagination.{current, next}`. Don't assume either field is present, check before reading it.
**Always check `search_metadata.status` first.** `"Success"` means proceed; `"Error"` means look at the message and don't trust the rest of the body.
---
## Pagination
Three patterns across the API. Know which one each engine uses.
### 1. Simple `page` (most engines)
`?page=1`, `?page=2`, etc. 1-indexed. The `pagination` block tells you next/last.
- Google family: 10 results per page (fixed)
- `google_local`: 20 per page
- Yahoo: 7 results per page
- Yandex: max 4 pages
- Zillow: max 24 pages
### 2. Token-based (Flights, Hotels, AI Overview, Shopping pipeline)
The response includes a token (`booking_token`, `departure_token`, `page_token`, `product_token`, `news_token`) you pass back to get the next step.
**AI Overview reality check:** the `google` engine's `ai_overview` comes back in two common shapes, varying per request: INLINE (`markdown`, `text_blocks`, `reference_links` present, no token) or TOKEN (`page_token` + `error`, body deferred). Read citations off the `google` response when inline; chain `google_ai_overview` on the token otherwise. `google_ai_overview` requires `page_token` as a REQUIRED input (sourced from a prior `google` SERP); calling it with only `q` returns a `400` (the required `page_token` is missing). Treat `google_ai_overview` as a fallback only when a `page_token` is actually present. When you do use it, the `page_token` expires in <1 minute, so chain follow-up calls without delay or refetch from scratch.
### 3. POST body for huge tokens
When pagination tokens get too long (especially `youtube_channel_videos` and `meta_ad_library`), passing them in the URL causes `414 URI Too Long`. Use POST with a JSON body instead:
```bash
curl -s -X POST "https://www.searchapi.io/api/v1/search" \
-H "Authorization: Bearer $SEARCHAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"engine":"youtube_channel_videos","channel_id":"UC...","page_token":"<huge_token>"}'
```
---
## Locale handling
Three knobs, used together or apart depending on the engine:
- `gl`, country (where the search "originates")
- `hl`, language (UI / result language preference)
- `location` (string) **or** `uule` (Google-encoded), physical location for engines that respect it (Search, Local, Maps, News, Shopping)
Rules:
- `location` and `uule` are mutually exclusive, pick one
- Most engines accept all of `gl`, `hl`, `location`/`uule`. A few only respect `gl`/`hl`.
- For Maps, use `ll=@lat,lng,zoom` for precise placement instead of `location` strings
---
## Rate limits + retry/backoff
**The hourly rate limit is 20% of your plan's monthly credits per hour.** Example: a plan with 10,000 monthly searches allows up to 2,000 searches in any single hour. Exceeding it returns `429` until the hour rolls over. Two practical implications:
- A single aggressive batch job can burn through your hourly window fast. For large keyword runs, spread calls across hours or size your plan for the burst, not just the monthly total.
Check [searchapi.io/pricing](https://www.searchapi.io/pricing) for current plan sizes.
**Retry pattern (exponential backoff):**
```python
import time, requests
def call_with_backoff(url, max_retries=5, base_delay=1.0):
for attempt in range(max_retries):
r = requests.get(url, timeout=30)
if r.status_code == 200:
return r.json()
if r.status_code == 429:
wait = base_delay * (2 ** attempt)
time.sleep(wait)
continue
if r.status_code >= 500:
wait = base_delay * (2 ** attempt)
time.sleep(wait)
continue
r.raise_for_status()
raise RuntimeError(f"Failed after {max_retries} retries")
```
Don't retry on `4xx` other than `429`. It's a request you constructed wrong.
---
## Error codes
| Status | Meaning | Action |
|---|---|---|
| `200` | Success, check `search_metadata.status` |
| `400` | Bad request (missing required param, invalid value) | Read `error` field, fix call |
| `401` | Invalid / missing API key | Re-export `SEARCHAPI_API_KEY` |
| `402` | Out of credits | Top up at dashboard |
| `403` | Forbidden (usually plan-tier feature gate) | Check `zero_retention` etc. is allowed on plan |
| `404` | Endpoint / resource not found | Wrong `engine=` slug? |
| `429` | Rate limited | Exponential backoff |
| `5xx` | Server error | Retry with backoff |
`search_metadata.status: "Error"` with `200` HTTP can happen when the request reached the parser but failed mid-flight. Read the `error` field.
---
## Cost optimization
SearchApi charges per call. To stay efficient:
1. **Use light variants when full detail isn't needed.** `google_light` is cheaper/faster than `google` when you don't need ads or AI Overview. Same for `google_images_light`, `google_videos_light`, `google_news_light`, `duckduckgo_light`.
2. **Cache aggressively.** Most SERPs change slowly, so a 24h cache on stable queries (such as rank tracking) avoids repeat charges.
3. **Narrow the query.** Asking `google` for a 100-result page no longer works (capped at 10); call `google_rank_tracking` instead if you genuinely need top-100 dedup'd.
4. **Batch detail lookups carefully.** When fanning out from a search to a detail engine (Shopping to product, YouTube search to transcripts), only fetch details for results you'll actually use.
5. **Avoid double-fetching.** `search_information.query_displayed` confirms what was actually searched. If it doesn't match your input, the query was rewritten, so don't re-fetch.
6. **Track spend.** Use `/api/v1/me` (see [Utility APIs](#utility--account-apis)) to monitor credits programmatically. Fields are NESTED, read `d['account']['remaining_credits']` and `d['api_usage']['searches_this_hour']` / `d['api_usage']['hourly_rate_limit']`.
---
## Architectural patterns to know
### Token-driven Shopping pipeline
```
google_shopping → product_token → google_product
→ google_product_offers
→ google_product_reviews
→ google_product_page (legacy product_id still works here)
```
Bing has the same pattern (`bing_shopping` → `bing_product`); treat its tokens as short-lived (lifespan is undocumented), so refetch rather than cache across requests.
### Maps pipeline
```
google_maps → data_id / place_id → google_maps_place
→ google_maps_reviews (topic_id now needs KGMID)
→ google_maps_photos
google_place uses KGMID (distinct from place_id/data_id), different shape, different sub-flow.
```
### Trends → News pipeline
```
google_trends_trending_now → news_token → google_trends_trending_now_news
```
### Three-tier ad library
Each network follows the same structure:
```
*_ad_library ← top-level search
*_advertiser_search / page_search ← filter to one advertiser
*_ad_details / page_info ← drill into one ad / page
```
Applies to Meta, Google Ads Transparency, TikTok Ads Library. LinkedIn currently only has the top-level search.
### Scholar citation graph
```
google_scholar_case_law → referenced_cases[].caselaw_id → recurse
```
### YouTube split (6 engines)
```
youtube (search) → id → youtube_video
→ youtube_transcripts
→ youtube_comments
→ youtube_channel
→ youtube_channel_videos
```
`youtube_trends` exists but is **deprecated** (YouTube killed Trending in July 2025).
---
## Engine families
For each family below: a short overview, the key engines table (name, docs URL, one-line "use when"), and per-family gotchas. **For full per-engine params + response shapes, look up the engine in [`ENGINES-REFERENCE.md`](../../ENGINES-REFERENCE.md).** Per-engine docs live at `https://www.searchapi.io/docs/<engine-slug-with-hyphens>`.
### Google Search family
| Engine (API) | Docs slug | Use when |
|---|---|---|
| `google` | `google` | Full Google SERP: organic, ads, AI Overview, knowledge graph, answer box. |
| `google_light` | `google-light-api` | Lighter/faster, no ads, no AI Overview. Cheaper. |
| `google_news` | `google-news` | News results |
| `google_news_light` | `google-news-light-api` | Lighter News variant |
| `google_news_portal` | `google-news-portal-api` | Structured news.google.com browsing (topic / section / publication / story tokens) |
| `google_videos` | `google-videos` | Video search across sources |
| `google_videos_light` | `google-videos-light-api` | Lighter video variant |
| `google_shorts` | `google-shorts-api` | YouTube Shorts via Google |
| `google_images` | `google-images` | Image search |
| `google_images_light` | `google-images-light-api` | Lighter image variant |
| `google_lens` | `google-lens` | **Image → search.** Input is an image URL. |
| `google_forums` | `google-forums-api` | Forum / Reddit / Quora content via Google |
| `google_autocomplete` | `google-autocomplete` | Google search-box suggestions, a keyword goldmine |
| `google_related_questions` | `google-related-questions-api` | "People Also Ask" expansion. |
| `google_ai_overview` | `google-ai-overview-api` | Fetches the AI Overview body when `google` returns the token shape (requires a `page_token`; otherwise read inline citations off the `google` response). |
| `google_ai_mode` | `google-ai-mode-api` | Google's AI Mode results |
| `google_about_this_domain` | `google-about-this-domain-api` | Domain reputation panel. |
| `google_rank_tracking` | `google-rank-tracking-api` | **Top-100 dedup'd snapshot in one call.** Best for rank tracking. Snapshot only, no history. |
**Family gotchas:** 10 results/page since Sept 2025 (no `num=100`). `google_domain` deprecated April 2025. AI Overview comes back inline or as a `page_token` you chain into `google_ai_overview` (the token expires in <1 minute); see Pagination above.
### Google Maps & Local
| Engine | Docs slug | Use when |
|---|---|---|
| `google_maps` | `google-maps` | Search Maps for businesses / POIs |
| `google_maps_place` | `google-maps-place` | Place details via `place_id` / `data_id` |
| `google_maps_reviews` | `google-maps-reviews` | Reviews (separate endpoint; `topic_id` now needs KGMID) |
| `google_maps_photos` | `google-maps-photos` | Place photos |
| `google_maps_directions` | `google-maps-directions-api` | Directions / distance / route between two points |
| `google_local` | `google-local-api` | Local pack from regular Google Search (different from Maps) |
| `google_place` | `google-place-api` | Place details via KGMID (distinct from `google_maps_place`) |
### Apple Maps
| Engine | Docs slug | Use when |
|---|---|---|
| `apple_maps` | `apple-maps-api` | Local business / place search on Apple Maps (the Apple-side parallel to `google_maps`) |
| `apple_maps_places` | `apple-maps-places-api` | Place details for an Apple Maps result, via its `place_id` |
### Google Shopping & products
| Engine | Docs slug | Use when |
|---|---|---|
| `google_shopping` | `google-shopping` | Shopping listings + prices + filters; mints `product_token` |
| `google_product` | `google-product` | Product detail by token |
| `google_product_page` | `google-product-page` | Product main page (legacy `product_id`/`prds` still works here only) |
| `google_product_offers` | `google-product-offers` | Cross-merchant offers for a product |
| `google_product_reviews` | `google-product-reviews` | Product reviews |
| `google_shopping_filters` | `google-shopping-filters` | Available filters for a shopping query |
| `google_shopping_autocomplete` | `google-shopping-autocomplete-api` | Shopping search suggestions |
| `google_about_this_store` | `google-about-this-store-api` | Store reputation panel |
**Gotchas:** `google_product_specs` deprecated (the engine now returns an error; use `google_product` for product detail). `product_id`/`prds` removed from `google_product` 2026-05-15, use `product_token` (legacy still works on `google_product_page`).
### Google travel
| Engine | Docs slug | Use when |
|---|---|---|
| `google_flights` | `google-flights-api` | Flight prices + emissions + booking |
| `google_flights_calendar` | `google-flights-calendar-api` | Price calendar across dates |
| `google_flights_location_search` | `google-flights-location-search-api` | Airport / city lookup |
| `google_hotels` | `google-hotels-api` | Hotels + vacation rentals |
| `google_hotels_property` | `google-hotels-property-api` | Property details |
| `google_hotels_autocomplete` | `google-hotels-autocomplete-api` | Hotel location autocomplete |
| `google_travel_explore` | `google-travel-explore-api` | **"Where can I go for $X?"** Fundamentally different from `google_flights` (specific route price) |
| `google_travel_explore_destination` | `google-travel-explore-destination-api` | Destination details from Travel Explore |
### Google research (Scholar, Patents, Books, Finance, Trends)
| Engine | Docs slug | Use when |
|---|---|---|
| `google_scholar` | `google-scholar` | Academic paper search |
| `google_scholar_author` | `google-scholar-author` | Author profile + publications |
| `google_scholar_cite` | `google-scholar-cite` | Citation export formats |
| `google_scholar_case_law` | `google-scholar-case-law-api` | US case law with citation graph |
| `google_patents` | `google-patents` | Patent search |
| `google_patents_details` | `google-patents-details` | Single patent details |
| `google_books` | `google-books-api` | Book search |
| `google_finance` | `google-finance` | Stock / forex / crypto / index data |
| `google_trends` | `google-trends` | Topic interest over time |
| `google_trends_trending_now` | `google-trends-trending-now-api` | Currently trending searches |
| `google_trends_trending_now_news` | `google-trends-trending-now-news-api` | News for a trending topic (via `news_token`) |
| `google_trends_autocomplete` | `google-trends-autocomplete` | Trends search-box autocomplete |
| `google_jobs` | `google-jobs` | Job listings |
| `google_events` | `google-events-api` | Local events |
### Google ads transparency
| Engine | Docs slug | Use when |
|---|---|---|
| `google_ads_transparency_center` | `google-ads-transparency-center-api` | Search Google ads by topic/keyword |
| `google_ads_transparency_center_advertiser_search` | `google-ads-transparency-center-advertiser-search-api` | Find advertisers |
| `google_ads_transparency_center_ad_details` | `google-ads-transparency-center-ad-details-api` | One ad's details + creative |
| `google_ads_advertiser_info` | `google-ads-advertiser-info-api` | Advertiser metadata |
### Bing family
| Engine | Docs slug | Use when |
|---|---|---|
| `bing` | `bing` | Bing web search |
| `bing_news` | `bing-news` | Bing news |
| `bing_images` | `bing-images-api` | Bing image search |
| `bing_videos` | `bing-videos-api` | Bing video search |
| `bing_shopping` | `bing-shopping-api` | Bing shopping listings (mints short-lived tokens) |
| `bing_product` | `bing-product-api` | Bing product detail by token, **refetch tokens, don't cache** |
### Other web search
| Engine | Docs slug | Use when |
|---|---|---|
| `yahoo` | `yahoo-api` | Yahoo Search, 7 results/page cap |
| `yandex` | `yandex-api` | Yandex Search, 4 pages max |
| `yandex_reverse_image` | `yandex-reverse-image-api` | Yandex reverse image search |
| `baidu` | `baidu` | Baidu (Chinese market) |
| `naver` | `naver-api` | Naver (Korean market) |
| `duckduckgo` | `duckduckgo-api` | DuckDuckGo web |
| `duckduckgo_light` | `duckduckgo-light-api` | Lightweight DuckDuckGo variant |
| `duckduckgo_images` | `duckduckgo-images-api` | DuckDuckGo image search |
| `duckduckgo_videos` | `duckduckgo-videos-api` | DuckDuckGo video search |
### E-commerce & marketplaces
| Engine | Docs slug | Use when |
|---|---|---|
| `amazon_search` | `amazon-search` | Amazon product search |
| `amazon_product` | `amazon-product` | Product details |
| `amazon_offers` | `amazon-offers-api` | All-merchant offers for an ASIN |
| `amazon_bestsellers` | `amazon-bestsellers-api` | Category bestsellers |
| `amazon_categories` | `amazon-categories-api` | Browse-node category hierarchy (params: `category_type`, `category_id`, `q`, `amazon_domain`, 23 Amazon domains) |
| `ebay_search` | `ebay-search-api` | eBay search |
| `ebay_product` | `ebay-product-api` | eBay product details |
| `walmart_search` | `walmart-search-api` | Walmart search |
| `walmart_product` | `walmart-product-api` | Walmart product |
| `walmart_reviews` | `walmart-reviews-api` | Walmart reviews |
| `bestbuy_search` | `bestbuy-search-api` | BestBuy search |
| `bestbuy_product` | `bestbuy-product-api` | BestBuy product |
### Travel / real estate
| Engine | Docs slug | Use when |
|---|---|---|
| `airbnb` | `airbnb-api` | Airbnb listing search |
| `airbnb_property` | `airbnb-property-api` | Listing details |
| `airbnb_property_reviews` | `airbnb-property-reviews-api` | Listing reviews |
| `airbnb_property_availability_calendar` | `airbnb-property-availability-calendar-api` | Availability calendar |
| `airbnb_experiences` | `airbnb-experiences-api` | Airbnb Experiences search |
| `airbnb_experience_details` | `airbnb-experience-details-api` | Experience details |
| `tripadvisor` | `tripadvisor-api` | TripAdvisor search |
| `tripadvisor_place` | `tripadvisor-place-api` | Place details |
| `tripadvisor_reviews` | `tripadvisor-reviews-api` | Reviews |
| `zillow` | `zillow-api` | Zillow real-estate listings, max 24 pages |
| `zillow_property` | `zillow-property-api` | Property details |
### YouTube (6 engines + 1 deprecated)
| Engine | Docs slug | Use when |
|---|---|---|
| `youtube` | `youtube` | YouTube search |
| `youtube_video` | `youtube-video` | Single video details |
| `youtube_transcripts` | `youtube-transcripts` | Auto / manual transcripts |
| `youtube_comments` | `youtube-comments` | Video comments |
| `youtube_channel` | `youtube-channel` | Channel info |
| `youtube_channel_videos` | `youtube-channel-videos-api` | All videos for a channel, **POST recommended** (huge tokens) |
| ~~`youtube_trends`~~ | ~~`youtube-trends`~~ | **Deprecated July 2025** |
### Social profiles
| Engine | Docs slug | Use when |
|---|---|---|
| `tiktok_profile` | `tiktok-profile-api` | TikTok user profile + posts |
| `facebook_business_page` | `facebook-business-page-api` | Facebook business page |
| `facebook_business_page_reviews` | `facebook-business-page-reviews-api` | Page reviews |
| `instagram_profile` | `instagram-profile-api` | Instagram profile + posts |
**Note:** No general TikTok scraper, only profile + ads library. Respect platform ToS for all social data.
### Ad libraries (Meta, LinkedIn, TikTok)
| Engine | Docs slug | Use when |
|---|---|---|
| `meta_ad_library` | `meta-ad-library-api` | Search Meta ads |
| `meta_ad_library_page_search` | `meta-ad-library-page-search-api` | Find pages |
| `meta_ad_library_ad_details` | `meta-ad-library-ad-details-api` | Single ad details |
| `meta_ad_library_page_info` | `meta-ad-library-page-info-api` | Page info |
| `linkedin_ad_library` | `linkedin-ad-library-api` | LinkedIn ads |
| `tiktok_ads_library` | `tiktok-ads-library-api` | TikTok ads, needs `advertiser_token` (NOT `advertiser_id`) |
| `tiktok_ads_library_ad_details` | `tiktok-ads-library-ad-details-api` | TikTok ad details |
| `tiktok_ads_library_advertiser_search` | `tiktok-ads-library-advertiser-search-api` | Find TikTok advertisers |
**Family gotchas:** Meta tokens can exceed URL length, so use POST. TikTok requires `advertiser_token` not `advertiser_id`.
### App stores
| Engine | Docs slug | Use when |
|---|---|---|
| `apple_app_store` | `apple-app-store` | Apple App Store search |
| `apple_product` | `apple-product-api` | Single app details |
| `apple_app_store_reviews` | `apple-app-store-reviews-api` | App reviews |
| `apple_app_store_top_charts` | `apple-app-store-top-charts-api` | Top charts |
| `google_play_store` | `google-play-store` | Play Store search |
| `google_play_product` | `google-play-product` | Single app details |
---
## Utility / account APIs
These are NOT search engines. They're account-management endpoints under `/api/v1/`.
| Endpoint | Docs | Purpose |
|---|---|---|
| `GET /api/v1/me` | `/docs/account-api` | Current account info. Fields are NESTED: `account.{current_month_usage, monthly_allowance, remaining_credits}` and `api_usage.{searches_this_hour, hourly_rate_limit}`, plus billing period |
| `GET /api/v1/locations` | `/docs/locations-api` | Look up valid `location` strings (returns `canonical_name`, `google_id`, `name`, `target_type`, `country_code`, `reach`, `lat`, `lon`) |
| `GET /api/v1/search_history` | `/docs/search-history-api` | List your past searches (last 90 days). **Requires an active subscription.** |
| `GET /api/v1/search_analytics` | `/docs/search-analytics-api` | Aggregated stats. **Requires Scale plan or above.** Params: `engine`, `bucket`, `time_period` (an enum), plus `time_period_min`/`time_period_max` for a custom range; a per-engine breakdown (`performance_by_engine`) is documented but not confirmable on a lower plan |
**Tips:** poll `/api/v1/me` to track credits (`account.remaining_credits`, and `api_usage.searches_this_hour` vs `hourly_rate_limit` for burst headroom); call `/api/v1/locations?q=Brooklyn` to get a valid `location` string.
---
## Deprecation log
Assume these are already in effect.
| Deprecated | Date | Replacement |
|---|---|---|
| `google_domain` + ccTLD params | 2025-04-15 | Use `gl`/`hl` |
| `num=100` (and other non-10 values) on Google | 2025-09-22 | Use `page` pagination; capped at 10/page |
| `google_product_specs` engine | 2025-10-02 (announced) | No direct replacement; the engine returns an error. Use `google_product` for product detail |
| `product_id` / `prds` on `google_product` family | 2026-05-15 | Use `product_token` (legacy still works on `google_product_page` only) |
| `youtube_trends` | 2025-07 | No replacement (YouTube killed Trending) |
| `topic_id` numeric on `google_maps_reviews` | recent | Use KGMID format |
---
## Choosing between similar engines
| Question | Pick |
|---|---|
| "Just give me top 100 Google results, dedup'd" | `google_rank_tracking` (snapshot only) |
| "Standard Google SERP with all features" | `google` |
| "Faster SERP when organic + knowledge graph + answer box + related questions is enough" | `google_light` |
| "Find Reddit/Quora threads" | `google_forums` |
| "Keyword research" | `google_autocomplete` |
| "PAA questions" | `google_related_questions` |
| "Am I in AI Overviews?" | Read `ai_overview` INLINE from the `google` response (`reference_links`, `markdown`, `text_blocks`); `google_ai_overview` is a fallback that needs a `page_token` |
| "Map-pack from regular Google" | `google_local` |
| "Maps search with full POI data" | `google_maps` |
| "Place details" | `google_maps_place` (place_id) vs `google_place` (KGMID), match the ID type you have |
| "Reviews for a place" | `google_maps_reviews` (separate endpoint, not via `data_id` on `google_maps`) |
| "Where can I go for $500?" | `google_travel_explore` (not `google_flights`) |
| "Specific route price" | `google_flights` |
| "Product details from a Shopping result" | `google_product` with `product_token` |
---
## Cheat sheet (the things you'll look up most)
**Engine name → docs URL:** Replace underscores with hyphens, but the `-api` suffix is inconsistent across engines (Google ones too: `/docs/google-maps` works, but it's `/docs/google-light-api`, `/docs/google-rank-tracking-api`, `/docs/google-ai-overview-api`). If the bare slug 404s, retry with `-api` appended. Per-engine slugs in [`ENGINES-REFERENCE.md`](../../ENGINES-REFERENCE.md) are verified.
**Base call:**
```bash
curl -s "https://www.searchapi.io/api/v1/search?engine=<engine>&q=<query>&api_key=$SEARCHAPI_API_KEY"
```
`engine=google` is the REST path. Over MCP, plain search is the tool `google_search_light` (REST engine `google_light`).
**Always check first:** `search_metadata.status` for `"Success"`.
**Locale defaults to US English** if no `gl`/`hl` set.
**Pagination:** `page=N` (1-indexed). Google = 10/page hardcoded.
**Long tokens / big bodies:** Use POST with JSON body.
**Cost-saving:** Use `*_light` variants, cache 24h, don't fetch details for results you won't use.
---
## When this skill doesn't have the answer
- Need the full param list for a specific engine? → [`ENGINES-REFERENCE.md`](../../ENGINES-REFERENCE.md) or `searchapi.io/docs/<engine-slug>`
- Need to do an SEO audit? → [`seo-audit`](../seo-audit/SKILL.md)
- Need to track AI Overviews? → [`ai-overview-tracking`](../ai-overview-tracking/SKILL.md)
- Need to spy on ads? → [`ads-monitor`](../ads-monitor/SKILL.md)
- Need an MCP bundle? → [`BUNDLES.md`](../../BUNDLES.md)
- First-time setup? → [`searchapi-onboarding`](../searchapi-onboarding/SKILL.md)
No comments yet. Be the first to comment!
