serper_sdk/
lib.rs

1/*!
2# Serper SDK
3
4A minimalistic yet ergonomic Rust SDK for the Serper Google Search API.
5
6## Features
7
8- **Type-safe API** with comprehensive error handling
9- **Modular architecture** with clear separation of concerns
10- **Async-first design** with concurrent request support
11- **Flexible configuration** with environment variable support
12- **Comprehensive testing** with extensive test coverage
13
14## Quick Start
15
16```rust
17use serper_sdk::{SearchService, SearchQuery, SearchResponse};
18
19fn main() -> Result<(), Box<dyn std::error::Error>> {
20    // Create a search service (with example API key for documentation)
21    let service = SearchService::new("demo-key-for-docs".to_string())?;
22
23    // Build a search query
24    let query = SearchQuery::new("Hamze Ghalebi CTO at Remolab".to_string())?
25        .with_location("Paris".to_string())
26        .with_page(1);
27
28    // Create a mock response for documentation example
29    let response = SearchResponse::new();
30
31    // Process results (in real usage, you'd use service.search(&query).await?)
32    println!("Query: {}", query.q);
33    println!("Location: {:?}", query.location);
34    println!("Results found: {}", response.organic_count());
35
36    Ok(())
37}
38```
39
40## Architecture
41
42The SDK is organized into several focused modules:
43
44- **`core`**: Fundamental types and error handling
45- **`search`**: Query construction and response parsing
46- **`http`**: Transport layer and HTTP client functionality
47- **`config`**: Configuration management
48- **`utils`**: Common utilities and helpers
49
50## Advanced Usage
51
52### Custom Configuration
53
54```rust
55use serper_sdk::{SearchService, http::TransportConfig};
56use std::time::Duration;
57
58fn main() -> Result<(), Box<dyn std::error::Error>> {
59    // Create service with custom configuration
60    let transport_config = TransportConfig::default()
61        .with_timeout(Duration::from_secs(60));
62
63    let service = SearchService::with_config(
64        "demo-key-for-docs".to_string(),
65        "https://google.serper.dev".to_string(),
66        transport_config
67    )?;
68
69    println!("Service created with custom 60s timeout");
70    Ok(())
71}
72```
73
74### Concurrent Searches
75
76```rust
77use serper_sdk::{SearchService, SearchQuery};
78
79fn main() -> Result<(), Box<dyn std::error::Error>> {
80    // Create service and queries
81    let _service = SearchService::new("demo-key-for-docs".to_string())?;
82
83    let queries = vec![
84        SearchQuery::new("Hamze Ghalebi CTO at Remolab".to_string())?,
85        SearchQuery::new("Hamze Ghalebi Remolab technology".to_string())?,
86        SearchQuery::new("Remolab France innovation".to_string())?,
87    ];
88
89    // In real usage: let results = service.search_concurrent(&queries, Some(3)).await?;
90    println!("Prepared {} queries for concurrent execution", queries.len());
91    for (i, query) in queries.iter().enumerate() {
92        println!("Query {}: {}", i + 1, query.q);
93    }
94
95    Ok(())
96}
97```
98
99### Query Builder Pattern
100
101```rust
102use serper_sdk::{SearchService, SearchQueryBuilder};
103
104fn main() -> Result<(), Box<dyn std::error::Error>> {
105    let _service = SearchService::new("demo-key-for-docs".to_string())?;
106
107    // Demonstrate the builder pattern
108    let query = SearchQueryBuilder::new()
109        .query("Hamze Ghalebi CTO at Remolab")
110        .location("Paris")
111        .country("fr")
112        .language("en")
113        .page(1)
114        .build()?;
115
116    println!("Built query: {}", query.q);
117    println!("Location: {:?}", query.location);
118    println!("Country: {:?}", query.gl);
119    println!("Language: {:?}", query.hl);
120    println!("Page: {:?}", query.page);
121
122    // In real usage: let response = service.search_with(|builder| { ... }).await?;
123    Ok(())
124}
125```
126*/
127
128// Core modules
129pub mod config;
130pub mod core;
131pub mod http;
132pub mod search;
133pub mod utils;
134
135// Re-export main types for convenience
136pub use config::{SdkConfig, SdkConfigBuilder};
137pub use core::{Result, SerperError};
138pub use search::{
139    AnswerBox, KnowledgeGraph, OrganicResult, SearchMetadata, SearchQuery, SearchQueryBuilder,
140    SearchResponse, SearchService,
141};
142
143// Legacy compatibility - re-export the main client for backward compatibility
144pub use search::SearchService as SerperClient;
serper_sdk/lib.rs

serper_sdk/
lib.rs
