SerpApi Reference Architecture Skill

SerpApi Reference Architecture

Overview

Production architecture for search-powered applications using SerpApi. Core components: cached search service, multi-engine abstraction, SERP monitoring pipeline, and credit budget management.

Architecture Diagram

┌──────────────────────────────────┐
│          API Layer               │
│  /search  /track  /health        │
├──────────────────────────────────┤
│        Search Service            │
│  Multi-engine  Caching  Parsing  │
├──────────────────────────────────┤
│       SerpApi Client             │
│  Rate Limiting  Retry  Archive   │
├──────────────────────────────────┤
│       Infrastructure             │
│  Redis Cache  PostgreSQL  Cron   │
└──────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────┐
│        SerpApi REST API          │
│  google  youtube  bing  news     │
│  1 credit/search, 100-50K/mo     │
└──────────────────────────────────┘

Project Structure

search-service/
├── src/
│   ├── serpapi/
│   │   ├── client.ts          # Cached search with rate limiting
│   │   ├── engines.ts         # Engine-specific param mapping
│   │   └── types.ts           # Typed result interfaces
│   ├── services/
│   │   ├── search.ts          # Multi-engine search facade
│   │   ├── tracking.ts        # Keyword rank tracking
│   │   └── credits.ts         # Usage monitoring
│   ├── api/
│   │   ├── search.ts          # /search proxy endpoint
│   │   └── health.ts          # /health with credit check
│   └── jobs/
│       └── rank-tracker.ts    # Daily keyword monitoring
├── tests/
│   ├── fixtures/              # Recorded SerpApi responses
│   └── search.test.ts         # Fixture-based tests
└── config/

Key Components

Search Service Facade

class SearchService {
  constructor(private client: CachedSerpApiClient, private db: Database) {}

  async search(query: string, options?: { engine?: string; num?: number }) {
    const engine = options?.engine || 'google';
    const result = await this.client.cachedSearch({
      engine, q: query, num: options?.num || 5,
    });

    // Normalize across engines
    return {
      results: result.organic_results || result.video_results || [],
      answer_box: result.answer_box || null,
      knowledge_graph: result.knowledge_graph || null,
      search_id: result.search_metadata.id,
      cached: result._cached || false,
    };
  }

  async trackKeyword(keyword: string, domain: string) {
    const result = await this.client.cachedSearch({
      engine: 'google', q: keyword, num: 100,
    });
    const position = result.organic_results?.findIndex(
      (r: any) => r.link?.includes(domain)
    );
    await this.db.saveRanking(keyword, domain, position >= 0 ? position + 1 : null);
  }
}

Credit Budget Manager

class CreditBudget {
  async check(): Promise<{ ok: boolean; remaining: number }> {
    const account = await fetch(
      `https://serpapi.com/account.json?api_key=${process.env.SERPAPI_API_KEY}`
    ).then(r => r.json());

    return {
      ok: account.plan_searches_left > 100,
      remaining: account.plan_searches_left,
    };
  }
}

Error Handling

| Component | Failure | Recovery | |-----------|---------|----------| | Search API | Credits exhausted | Return cached results, alert ops | | Cache | Redis down | Fall through to API (graceful degradation) | | Rank tracker | Query fails | Skip and retry next cycle | | Health check | API unreachable | Report degraded status |

Resources

Next Steps

See individual skill docs for deep-dives on each component.

Agent Skills: SerpApi Reference Architecture

Install this agent skill to your local

Skill Files