Struct SerpClientBuilder 

pub struct SerpClientBuilder { /* private fields */ }

A builder for constructing SerpClient instances with custom configuration.

The builder pattern provides a flexible and type-safe way to configure the client with various options. All configuration methods return self for method chaining.

Default Configuration

• Timeout: 30 seconds
• Retry Policy: Default policy with exponential backoff
• Base URL: https://serpapi.com
• User Agent: serp-sdk-rust/{version}

Configuration Options

• api_key: Set the SerpAPI authentication key
• timeout: Configure request timeout duration
• retry_policy: Set custom retry behavior
• user_agent: Override the User-Agent header
• base_url: Use a custom API endpoint
• default_header: Add custom headers to all requests

Examples

Basic Configuration

let client = SerpClient::builder()
    .api_key("your-api-key")
    .build()?;

Full Configuration

let client = SerpClient::builder()
    .api_key("your-api-key")
    .timeout(Duration::from_secs(60))
    .retry_policy(
        RetryPolicy::new(3)
            .with_base_delay(Duration::from_millis(500))
            .with_max_delay(Duration::from_secs(30))
    )
    .user_agent("my-search-app/2.0")
    .default_header("X-Custom-Header", "value")?
    .build()?;

Using Environment Variables

// API key will be read from SERP_API_KEY environment variable
std::env::set_var("SERP_API_KEY", "your-api-key");
let client = SerpClient::builder().build()?;

Implementations

impl SerpClientBuilder

pub fn new() -> Self

Creates a new client builder with default settings.

The default configuration is suitable for most use cases:

• 30-second timeout
• Standard retry policy with exponential backoff
• Official SerpAPI endpoint

Examples

use serp_sdk::SerpClient;

let builder = SerpClient::builder();

pub fn api_key(self, key: impl Into<String>) -> Self

Sets the API key for authentication.

The API key is required for all SerpAPI requests. You can obtain one by signing up at https://serpapi.com.

Arguments

• key - The SerpAPI authentication key

Examples

let client = SerpClient::builder()
    .api_key("your-secret-api-key")
    .build()?;

pub fn base_url(self, url: impl Into<String>) -> Self

Sets a custom base URL for the API.

This is useful for:

• Using a proxy server
• Connecting to a mock server for testing
• Using a regional endpoint

Arguments

• url - The base URL (without trailing slash)

Examples

let client = SerpClient::builder()
    .api_key("test-key")
    .base_url("https://proxy.example.com")
    .build()?;

pub fn timeout(self, timeout: Duration) -> Self

Sets the request timeout duration.

This timeout applies to the entire request/response cycle, including:

• DNS resolution
• TCP connection
• TLS handshake
• Request transmission
• Response reception

Arguments

• timeout - Maximum duration for a single request

Examples

let client = SerpClient::builder()
    .api_key("key")
    .timeout(Duration::from_secs(60))  // 1 minute timeout
    .build()?;

pub fn retry_policy(self, policy: RetryPolicy) -> Self

Sets the retry policy for handling transient failures.

The retry policy determines:

• Maximum number of retry attempts
• Delay between retries (with exponential backoff)
• Jitter for avoiding thundering herd

Arguments

• policy - Custom retry policy configuration

Examples

let policy = RetryPolicy::new(5)
    .with_base_delay(Duration::from_millis(100))
    .with_max_delay(Duration::from_secs(60))
    .with_jitter(true);

let client = SerpClient::builder()
    .api_key("key")
    .retry_policy(policy)
    .build()?;

pub fn user_agent(self, agent: impl Into<String>) -> Self

Sets a custom User-Agent header.

The User-Agent identifies your application to the API server. This can be useful for debugging and analytics.

Arguments

• agent - User-Agent string

Examples

let client = SerpClient::builder()
    .api_key("key")
    .user_agent("MySearchApp/1.0 (contact@example.com)")
    .build()?;

pub fn default_header( self, name: impl AsRef<str>, value: impl AsRef<str>, ) -> SerpResult<Self>

Adds a default header to all requests.

Custom headers are useful for:

• Adding authentication tokens
• Setting correlation IDs for tracing
• Adding custom metadata

Arguments

• name - Header name
• value - Header value

Returns

Returns Result<Self> as header parsing can fail for invalid names/values.

Examples

let client = SerpClient::builder()
    .api_key("key")
    .default_header("X-Request-ID", "abc123")?
    .default_header("X-Client-Version", "2.0")?
    .build()?;

pub fn build(self) -> SerpResult<SerpClient>

Builds the configured SerpClient instance.

This method validates the configuration and creates the client. It will fail if:

• No API key is provided (via builder or environment)
• The API key is empty or whitespace-only
• HTTP client construction fails

Returns

Returns Result<SerpClient> which will be:

• Ok(client) if configuration is valid
• Err(SerpError) if configuration is invalid

Examples

let client = SerpClient::builder()
    .api_key("your-api-key")
    .build()?;

assert!(client.is_configured());

Errors

• SerpError::MissingApiKey: No API key provided
• SerpError::InvalidParameter: API key is empty
• SerpError::ClientBuilder: HTTP client construction failed

Trait Implementations

impl Default for SerpClientBuilder

fn default() -> Self

Returns the “default value” for a type.