Skip to content
Skills Library
Programming · Building & coding

serpapi-sdk-patterns

/serpapi-sdk-patterns

Wrap the official SerpAPI Python or JavaScript client behind typed, testable boundaries with safe errors, pagination, and output selection. Use when production code needs a stable search adapter. Trigger with "design a SerpAPI client wrapper".

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Wrap the official SerpAPI Python or JavaScript client behind typed, testable boundaries with safe errors, pagination, and output selection. Use when production code needs a stable search adapter. Trigger with "design a SerpAPI client wrapper".

Triggers from the description

design a SerpAPI client wrapper

Arguments

/serpapi-sdk-patterns [python|typescript] [engine]
Original author description

Wrap the official SerpAPI Python or JavaScript client behind typed, testable boundaries with safe errors, pagination, and output selection. Use when production code needs a stable search adapter. Trigger with "design a SerpAPI client wrapper".

How it works

  1. Overview
  2. Prerequisites
  3. Tool Discipline
  4. Current Contract
  5. Authentication
  6. Instructions
  7. Output
  8. Error Handling
  9. Example
  10. Resources
Original SKILL.md headings · 75 lines, 454 words
SKILL.md preview
---
name: serpapi-sdk-patterns
description: 'Wrap the official SerpAPI Python or JavaScript client behind typed, testable boundaries with safe errors, pagination, and output selection. Use when production code needs a stable search adapter. Trigger with "design a SerpAPI client wrapper".'
argument-hint: "[python|typescript] [engine]"
allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit
version: 1.6.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags: [saas, serpapi, sdk, architecture, typescript]
model: inherit
effort: high
compatibility: Designed for Claude Code; live client verification requires a separately approved key and allowance
---
# SerpAPI Production Client Patterns

## Overview

Create a narrow application-owned gateway instead of spreading vendor parameters, credentials, and variable result schemas through business code.

## Prerequisites

- A selected official client and pinned dependency version
- Supported engines, required output fields, latency objective, and failure policy
- Sanitized fixtures for each supported response shape

## Tool Discipline

Use `Read`, `Glob`, and `Grep` to map current call sites and types, `WebFetch` to verify official client interfaces, and `Write` or `Edit` for the gateway, schemas, fixtures, and tests.

## Current Contract

The Python client returns a `SerpResults` mapping and provides `next_page()` and `yield_pages()`. The JavaScript client exposes promise and callback forms including `getJson`, `getJsonBySearchId`, and `getAccount`, but does not provide built-in pagination. Search output can be JSON, HTML, or Markdown; `json_restrictor` can reduce JSON payload fields.

## Authentication

Inject `SERPAPI_KEY` at the outer server-side composition root. Do not include it in domain types, cache keys, error objects, telemetry, or serialized request parameters.

## Instructions

1. Define a request type that admits only supported engines and application-controlled locale, safety, pagination, and output options.
2. Define a normalized response type with explicit optional sections and vendor metadata isolated from domain data.
3. Inject the official client behind a small interface so fixtures can replace it without network interception.
4. Centralize timeouts, bounded retry for transient failures, 429 classification, redaction, and search-ID logging.
5. For Python, use `yield_pages()` only with a page/search budget; for JavaScript, implement engine-specific manual pagination from documented tokens or offsets.
6. Select JSON for structured parsing, Markdown for token-efficient agent consumption, HTML only for approved debugging, and `json_restrictor` when supported fields are known.
7. Add contract tests for empty-success, optional sections, processing/error states, pagination termination, timeout, and redaction.

## Output

Return request and response types, gateway code, client-version pin, pagination and retry budgets, output-selection rationale, fixture tests, and redaction evidence.

## Error Handling

| Condition | Response |
|---|---|
| Unknown engine or parameter | Reject locally before making a request. |
| Python `HTTPError` or `TimeoutError` | Map to a typed application error and preserve safe status/search metadata. |
| JavaScript rejection | Normalize the status and message without serializing request credentials. |
| Pagination budget reached | Return an explicit partial result and continuation state. |

## Example

```typescript
import { getJson } from "serpapi";

export async function searchGoogle(query: string) {
  const result = await getJson({
    engine: "google",
    q: query,
    api_key: process.env.SERPAPI_KEY,
    json_restrictor: "organic_results[].{position,title,link}",
  });
  return (result.organic_results ?? []).map(({ position, title, link }) => ({
    position, title, link,
  }));
}
```

## Resources

- [Official Python client](https://github.com/serpapi/serpapi-python)
- [Official JavaScript client](https://github.com/serpapi/serpapi-javascript)
- [JSON Restrictor](https://serpapi.com/json-restrictor)

## Next Steps

Exercise the gateway against sanitized fixtures, then canary one approved live request per supported engine.

Versions

The database has no other skills named serpapi-sdk-patterns.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version ffbf8c117921 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100serpapi-upgrade-migration
    Migrate legacy SerpAPI Python or JavaScript packages and response assumptions to current official clients with contract tests and rollback. Use when performing dependency or API upgrades. Trigger with "migrate a SerpAPI client".
  • 100serpapi-install-auth
    Install an official SerpAPI client, configure the private API key for server-side use, and verify account access without leaking credentials. Use when starting or repairing a SerpAPI integration. Trigger with "configure SerpAPI access".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.