keyapi-google-search

Perform Google web and image searches — retrieve ranked web results or search for images with geographic, language, and result-count controls.

This skill provides Google search intelligence using the KeyAPI MCP service. It enables keyword-based web search returning ranked results with titles, URLs, and snippets, and image search with country/language targeting and page-based pagination — all through a unified, cache-first workflow.

Use this skill when you need to:

• Retrieve ranked Google web search results for any keyword query
• Search Google Images for visual content matching a keyword
• Target searches to a specific country or language
• Control result count (up to 100 for web, up to 20 per page for images)
• Paginate through image search results

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Prerequisites

Requirement	Details
KEYAPI_TOKEN	A valid API token from keyapi.ai. Register at the site to obtain your free token. Set it as an environment variable: export KEYAPI_TOKEN=your_token_here
Node.js	v18 or higher
Dependencies	Run npm install in the skill directory to install @modelcontextprotocol/sdk

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

MCP Server Configuration

All tool calls in this skill target the KeyAPI Google MCP server:

Server URL : https://mcp.keyapi.ai/google/mcp
Auth Header: Authorization: Bearer $KEYAPI_TOKEN

Setup (one-time):

# 1. Install dependencies
npm install

# 2. Set your API token (get one free at https://keyapi.ai/)
export KEYAPI_TOKEN=your_token_here

# 3. List all available tools to verify the connection
node scripts/run.js --platform google --list-tools

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Analysis Scenarios

User Need	Node(s)	Best For
Ranked web search results	web_search	Content research, competitive analysis, SERP monitoring
Image search results	image_search	Visual content discovery, brand image monitoring, asset research

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Workflow

Step 1 — Select the Right Search Node

• Web content research: Use web_search for any query requiring text results, URLs, and page snippets.
• Visual content research: Use image_search for queries requiring image URLs and visual asset discovery.

web_search — No Pagination

web_search returns results in a single call. Use the num parameter (1–100) to control how many results are returned. There is no page parameter — all results are delivered at once.

image_search — Page-Based Pagination

image_search supports page (1-indexed) and num (1–20 per page) for pagination. To retrieve more results, increment the page value while keeping num consistent.

Language and Region Targeting

The two endpoints use different parameter conventions for targeting:

Endpoint	Language param	Format	Example
web_search	lr	Language-region code	en-US, zh-CN, de-DE
image_search	lr	Language prefix code	lang_en, lang_zh-CN, lang_de
image_search	gl	Two-letter country code	us, cn, de

For web_search, lr controls both language and regional relevance. For image_search, use gl for country targeting and lr for language filtering — they are independent controls.

Step 2 — Retrieve API Schema

Before calling any node, inspect its input schema to confirm required parameters and available options:

node scripts/run.js --platform google --schema web_search
node scripts/run.js --platform google --schema image_search

Step 3 — Call APIs and Cache Results Locally

Execute tool calls and persist responses to the local cache to avoid redundant API calls.

Calling a tool:

# Single call with pretty output
node scripts/run.js --platform google --tool <tool_name> \
  --params '<json_args>' --pretty

# Force fresh data, skip cache
node scripts/run.js --platform google --tool <tool_name> \
  --params '<json_args>' --no-cache --pretty

Example — web search (English, US, top 10 results):

node scripts/run.js --platform google --tool web_search \
  --params '{"q":"best noise cancelling headphones 2025","lr":"en-US","num":10}' --pretty

Example — web search (more results in one call):

node scripts/run.js --platform google --tool web_search \
  --params '{"q":"competitor analysis tools","lr":"en-US","num":50}' --pretty

Example — image search (first page):

node scripts/run.js --platform google --tool image_search \
  --params '{"q":"wireless earbuds product photography","gl":"us","lr":"lang_en","num":20,"page":1}' --pretty

Example — image search (next page):

node scripts/run.js --platform google --tool image_search \
  --params '{"q":"wireless earbuds product photography","gl":"us","lr":"lang_en","num":20,"page":2}' --pretty

Example — web search in a non-English market:

node scripts/run.js --platform google --tool web_search \
  --params '{"q":"无线耳机推荐","lr":"zh-CN","num":10}' --pretty

Pagination reference:

Endpoint	Pagination	Notes
web_search	None	Use num (1–100) to set result count. All results returned in one call.
image_search	page (1-indexed)	Use num (1–20) per page. Increment page for next batch.

Parameter reference:

Endpoint	Parameter	Description	Example values
Both	q	Search query (required)	"best headphones"
web_search	num	Result count (1–100, default 10)	10, 50, 100
web_search	lr	Language and region (default en-US)	en-US, zh-CN, de-DE, ja-JP
image_search	num	Results per page (1–20, default 10)	10, 20
image_search	page	Page number (1-indexed, default 1)	1, 2, 3
image_search	gl	Country code for geo-targeting (default us)	us, uk, de, cn
image_search	lr	Language filter (default lang_en)	lang_en, lang_zh-CN, lang_de

Cache directory structure:

.keyapi-cache/
└── YYYY-MM-DD/
    ├── web_search/
    │   └── {params_hash}.json
    └── image_search/
        └── {params_hash}.json

Cache-first policy:

Before every API call, check whether a cached result already exists for the given parameters. If a valid cache file exists, load from disk and skip the API call.

Step 4 — Synthesize and Report Findings

After collecting all API responses, produce a structured search intelligence report:

For web search results:

1. SERP Overview — Total result count, top-ranking domains, result type distribution (organic, featured snippets, knowledge panels).
2. Content Analysis — Key themes across top results, common title patterns, snippet sentiment.
3. Competitive Landscape — Dominant domains, content authority signals, outranking opportunities.
4. Research Findings — Synthesized answer from top results relevant to the query intent.

For image search results:

1. Image Inventory — Result count, image source domains, image type distribution (product photos, infographics, logos).
2. Visual Themes — Common subjects, color patterns, composition styles.
3. Source Attribution — Top domains providing images, licensing signals where available.

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Common Rules

Rule	Detail
web_search has no pagination	Use num (max 100) to retrieve all desired results in one call. There is no page parameter for web search.
image_search pagination	Use page (1-indexed) with consistent num to paginate through image results.
lr format difference	web_search uses en-US format; image_search uses lang_en format. Do not mix them.
gl is image-search only	The gl country-targeting parameter is available on image_search only, not web_search.
num limits	web_search: 1–100. image_search: 1–20 per page.
Success check	code = 0 → success. Any other value → failure. Always check the response code before processing data.
Retry on 500	If code = 500, retry the identical request up to 3 times with a 2–3 second pause between attempts before reporting the error.
Cache first	Always check the local .keyapi-cache/ directory before issuing a live API call.

author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills

Error Handling

Code	Meaning	Action
0	Success	Continue workflow normally
400	Bad request — invalid or missing parameters	Ensure q is provided; check num range (web: 1–100, image: 1–20); verify lr format
401	Unauthorized — token missing or expired	Confirm KEYAPI_TOKEN is set correctly; visit keyapi.ai to renew
403	Forbidden — plan quota exceeded or feature restricted	Review plan limits at keyapi.ai
429	Rate limit exceeded	Wait 60 seconds, then retry
500	Internal server error	Retry up to 3 times with a 2–3 second pause; if it persists, log the full request and response and skip this node
Other non-0	Unexpected error	Log the full response body and surface the error message to the user