---

name: serpapi-upgrade-migration description: '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".' argument-hint: "[python|javascript] [from-version] [to-version]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit, Bash(python3:), Bash(npm:) version: 1.6.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, serpapi, migration, python, javascript] model: inherit effort: high compatibility: Designed for Claude Code; dependency installation, live comparison, and production rollout require repository and account-owner approval

SerpAPI Client Upgrade and Migration

Overview

Inventory actual legacy behavior, introduce the current official client behind a seam, and prove response and failure compatibility before removing the old path.

Prerequisites

• Current dependency locks, imports, call sites, engine parameters, fixtures, and runtime support matrix
• Target official client release notes and migration documentation
• Search budget, canary environment, rollback owner, and immutable baseline

Tool Discipline

Use Read, Glob, and Grep to inventory dependencies and behavior, WebFetch to verify current official packages, Write or Edit for the adapter and tests, and Bash(python3:*) or Bash(npm:*) only for approved installs and test execution.

Current Contract

The recommended Python distribution is serpapi, distinct from the legacy google-search-results distribution. Its Client.search returns a SerpResults mapping with helpers such as as_dict() and pagination methods. The current JavaScript serpapi package supports promises and callbacks; migration from google-search-results-nodejs must preserve engine parameters and error behavior explicitly.

Authentication

Keep the existing server-side SERPAPI_KEY boundary unchanged during migration. Never copy credentials into migration scripts, lockfiles, fixtures, dual-run telemetry, or exception snapshots.

Instructions

1. Pin the baseline and inventory package names, versions, imports, engine-specific classes, callbacks, result conversions, pagination, timeouts, retries, and error handling.
2. Re-fetch target release notes and build a behavior matrix for requests, result type, archive access, pagination, and exceptions.
3. Add an application-owned gateway and run both implementations against the same sanitized fixtures.
4. Update Python code from legacy engine classes to current client calls, or JavaScript callbacks to the chosen promise/callback form, without mixing semantic changes.
5. Regenerate the dependency lock and run static, unit, fixture, failure-path, and packaging tests.
6. With approval, compare one harmless live request through each path or use a single captured response when duplicate searches are unnecessary.
7. Canary the new path behind a flag, reconcile outputs and capacity, then remove the legacy dependency only after rollback criteria hold.

Output

Return the baseline and target versions, behavior matrix, changed call sites, lockfile diff, fixture/live comparison, canary evidence, legacy removal decision, and rollback plan.

Error Handling

Condition	Response
Result treated as an exact plain dict	Update types to the documented mapping or call as_dict() where an exact dictionary is required.
Error behavior changes	Normalize exceptions in the gateway before rollout.
Engine parameters drift	Restore parity and test each engine independently.
Dual-run doubles usage	Stop duplicate live calls and compare from one sanitized capture.

Example

# Current official Python client
import os
import serpapi

client = serpapi.Client(api_key=os.environ["SERPAPI_KEY"], timeout=10)
result = client.search({"engine": "google", "q": "coffee"})
plain_result = result.as_dict()

Resources

• Official Python client
• Official JavaScript client
• JavaScript migration guide

Next Steps

Remove the feature flag only after a full observation window and archive the rollback receipt.