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
KEYAPITOKEN	A valid API token from keyapi.ai. Register at the site to obtain your free token. Set it as an environment variable: INLINECODE0
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:

CODEBLOCK0

Setup (one-time):

CODEBLOCK1

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

---

Analysis Scenarios

User Need	Node(s)	Best For
Ranked web search results	INLINECODE3	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
INLINECODE17	INLINECODE18	Language-region code	INLINECODE19, zh-CN, INLINECODE21
INLINECODE22

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:

CODEBLOCK2

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:

CODEBLOCK3

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

CODEBLOCK4

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

CODEBLOCK5

Example — image search (first page):

CODEBLOCK6

Example — image search (next page):

CODEBLOCK7

Example — web search in a non-English market:

CODEBLOCK8

Pagination reference:

Endpoint	Pagination	Notes
INLINECODE37	None	Use num (1–100) to set result count. All results returned in one call.
INLINECODE39

page (1-indexed) | Use num (1–20) per page. Increment page for next batch. |

Parameter reference:

Endpoint	Parameter	Description	Example values
Both	INLINECODE43	Search query (required)	INLINECODE44
INLINECODE45

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:

CODEBLOCK9

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. 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. 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
INLINECODE100	Success	Continue workflow normally
INLINECODE101

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 |