Getting Started¶

Installation¶

Go Package¶

go get github.com/plexusone/omniserp@latest

CLI Tool¶

go install github.com/plexusone/omniserp/cmd/omniserp@latest

MCP Server¶

go install github.com/plexusone/omniserp/cmd/mcp-omniserp@latest

Configuration¶

Environment Variables¶

OmniSerp uses environment variables for configuration:

# Choose which engine to use (optional, defaults to "serper")
export SEARCH_ENGINE="serper"  # or "serpapi"

# API keys for respective engines
export SERPER_API_KEY="your_serper_key"
export SERPAPI_API_KEY="your_serpapi_key"

Getting API Keys¶

Serper.dev¶

Visit serper.dev
Sign up for an account
Copy your API key from the dashboard
Set the environment variable: export SERPER_API_KEY="your_key"

SerpAPI¶

Visit serpapi.com
Sign up for an account
Copy your API key from your account settings
Set the environment variable: export SERPAPI_API_KEY="your_key"

Basic Usage¶

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/plexusone/omniserp"
    "github.com/plexusone/omniserp/client"
)

func main() {
    // Create client (auto-selects engine based on SEARCH_ENGINE env var)
    c, err := client.New()
    if err != nil {
        log.Fatalf("Failed to create client: %v", err)
    }

    log.Printf("Using engine: %s v%s", c.GetName(), c.GetVersion())

    // Perform a search
    result, err := c.Search(context.Background(), omniserp.SearchParams{
        Query:      "golang programming",
        NumResults: 10,
        Language:   "en",
        Country:    "us",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Use the result
    log.Printf("Search completed: %+v", result.Data)
}

Selecting a Specific Engine¶

// Create client with a specific engine
c, err := client.NewWithEngine("serpapi")
if err != nil {
    log.Fatal(err)
}

// Or switch engines at runtime
c.SetEngine("serper")

Testing¶

Run tests without API keys (tests will skip gracefully):

go test ./...

Run tests with API calls (requires API keys):

export SERPER_API_KEY="your_key"
export SERPAPI_API_KEY="your_key"
go test -v ./client