serp-sdk 0.2.1

A comprehensive, production-ready Rust SDK for SerpAPI with async support, type safety, and ergonomic APIs. Developed during the Realtime Search AI Hackathon powered by SerpAPI.
Documentation

SerpAPI Rust SDK

Crates.io Documentation License Build Status codecov Rust Version

A comprehensive, production-ready Rust SDK for the SerpAPI service that provides ergonomic APIs, type safety, and async-first design.

🏆 Developed during the Realtime Search AI Hackathon (Hybrid) powered by SerpAPI and organized by AI Tinkerers Paris

Features

  • 🦀 Type-safe: Strongly typed request builders and response structures
  • ⚡ Async/await: Built on tokio with efficient async I/O
  • 🎯 Ergonomic: Fluent builder APIs for constructing queries
  • 🔄 Resilient: Automatic retry logic with exponential backoff
  • 🌊 Streaming: Support for paginated result streaming
  • 🏭 Production-ready: Comprehensive error handling and logging
  • 🔍 Specialized: Built-in support for images, news, videos, shopping, and local search

Quick Start

Add this to your Cargo.toml:

[dependencies]
serp-sdk = "0.1"
tokio = { version = "1.0", features = ["full"] }

Documentation

To generate local documentation:

cargo doc --all-features --no-deps --open

Basic Usage

use serp_sdk::{SerpClient, SearchQuery};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client (API key from env var SERP_API_KEY or builder)
    let client = SerpClient::builder()
        .api_key("your-serp-api-key")
        .build()?;

    // Build and execute search
    let results = client.search(
        SearchQuery::new("Rust programming language")
            .language("en")
            .country("us")
            .limit(10)?
    ).await?;

    // Process results
    if let Some(organic) = results.organic_results {
        for result in organic {
            println!("{}: {}", result.title, result.link);
        }
    }

    Ok(())
}

Advanced Features

Streaming Results

Stream paginated results for large queries:

use futures::StreamExt;
use serp_sdk::{SerpClient, SearchQuery, StreamConfig};

let mut stream = client.search_stream(
    SearchQuery::new("rust tutorials"),
    StreamConfig::new()
        .page_size(20)?
        .max_pages(5)
        .delay(std::time::Duration::from_millis(500))
);

while let Some(page) = stream.next().await {
    match page {
        Ok(results) => println!("Got page with {} results",
            results.organic_results.as_ref().map_or(0, |r| r.len())),
        Err(e) => eprintln!("Error: {}", e),
    }
}

Specialized Search Types

Image Search

let images = client.search(
    SearchQuery::new("rust logo").images()
).await?;

News Search

let news = client.search(
    SearchQuery::new("rust programming").news()
).await?;

Video Search

let videos = client.search(
    SearchQuery::new("rust tutorial").videos()
).await?;

Shopping Search

let products = client.search(
    SearchQuery::new("rust book").shopping()
).await?;

Local Search

let local = client.search(
    SearchQuery::new("rust meetup")
        .location("San Francisco, CA")
).await?;

Advanced Query Building

let results = client.search(
    SearchQuery::new("site:github.com rust web framework")
        .language("en")
        .country("us")
        .device("desktop")
        .safe_search("off")
        .domain("google.com")
        .limit(50)?
        .offset(10)
).await?;

Error Handling

The SDK provides comprehensive error handling with the SerpError enum:

match client.search(query).await {
    Ok(results) => {
        // Process results
    }
    Err(SerpError::RateLimited { retry_after }) => {
        println!("Rate limited, retry after {} seconds", retry_after);
    }
    Err(SerpError::ApiError { code, message }) => {
        println!("API error {}: {}", code, message);
    }
    Err(SerpError::MissingApiKey) => {
        println!("Please set SERP_API_KEY environment variable");
    }
    Err(e) => {
        println!("Other error: {}", e);
    }
}

Retry Policy Configuration

use serp_sdk::RetryPolicy;
use std::time::Duration;

let client = SerpClient::builder()
    .api_key("your-key")
    .retry_policy(
        RetryPolicy::new(5) // Max 5 retries
            .with_base_delay(Duration::from_millis(200))
            .with_max_delay(Duration::from_secs(30))
            .with_backoff_multiplier(2.0)
    )
    .build()?;

Configuration

Environment Variables

  • SERP_API_KEY: Your SerpAPI key (if not provided via builder)

Client Configuration

let client = SerpClient::builder()
    .api_key("your-key")
    .base_url("https://serpapi.com") // Custom base URL
    .timeout(Duration::from_secs(30)) // Request timeout
    .user_agent("my-app/1.0") // Custom User-Agent
    .default_header("X-Custom", "value")? // Add custom headers
    .build()?;

Response Types

The SDK provides strongly-typed response structures:

  • SearchResults: Complete search response
  • OrganicResult: Individual organic search result
  • AnswerBox: Featured snippet/answer box
  • KnowledgeGraph: Knowledge panel information
  • NewsResult: News article result
  • VideoResult: Video search result
  • ShoppingResult: Shopping/product result
  • LocalPlace: Local business result

Examples

The repository includes comprehensive examples:

Run examples with:

# Set your API key
export SERP_API_KEY="your-serp-api-key"

# Run basic search example
cargo run --example basic_search

# Run streaming example
cargo run --example streaming

# Run specialized search example
cargo run --example specialized_search

Testing

Run the test suite:

cargo test

Run with logging:

RUST_LOG=debug cargo test

Features

  • streaming: Enable streaming support (enabled by default)
  • mcp: Enable MCP (Model Context Protocol) integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Performance

The SDK is designed for high performance with minimal overhead:

  • Query Building: ~54ns for simple queries, ~113ns for complex queries
  • HTTP Client: Built on reqwest with connection pooling and keepalive
  • Memory Efficient: Streaming support prevents large result sets from consuming excessive memory
  • Zero-Cost Abstractions: Leverages Rust's type system for compile-time guarantees

Roadmap

Sponsors

This project is supported by our generous sponsors:

Acknowledgments

  • AI Tinkerers Paris - For organizing the hackathon and fostering AI innovation
  • SerpAPI - For providing the excellent search API service and sponsoring the hackathon
  • The Rust community for exceptional async and HTTP libraries
  • All contributors who help improve this project

Team

This SDK was developed by:

Roadmap

📍 See ROADMAP.md for detailed implementation plans

Summary

This SDK is evolving into a comprehensive AI-powered search infrastructure through three strategic phases:

  1. 🎯 Rig Integration (Q1 2026): Transform the SDK into an intelligent search layer for LLM applications, enabling RAG pipelines, semantic search, and AI agent tools.

  2. 🗄️ PostgreSQL Integration (Q2 2026): Add persistent caching, search analytics, and query optimization with database-backed storage for enterprise-scale deployments.

  3. 🌐 MCP Server (Q3 2026): Expose search capabilities to AI assistants through the Model Context Protocol, enabling multi-assistant collaboration.