anyserp

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2026 License: MIT Imports: 12 Imported by: 0

README

anyserp-go

Unified SERP API router for Go. Route search requests across Google, Bing, Brave, and more with a single API. Self-hosted, zero fees.

Install

go get github.com/probeo-io/anyserp-go

Quick Start

Set your API keys as environment variables:

export SERPER_API_KEY=...
export BRAVE_API_KEY=...

package main

import (
    "context"
    "fmt"

    serp "github.com/probeo-io/anyserp-go"
)

func main() {
    client := serp.New(nil) // reads API keys from env vars

    // Search with the first available provider
    results, err := client.Search(context.Background(), serp.SearchRequest{
        Query: "best go frameworks",
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(results.Results[0].Title, results.Results[0].URL)
}

Supported Providers

Provider Env Var Web Images News Videos
Serper SERPER_API_KEY Yes Yes Yes Yes
SerpAPI SERPAPI_API_KEY Yes Yes Yes Yes
Google CSE GOOGLE_CSE_API_KEY + GOOGLE_CSE_ENGINE_ID Yes Yes No No
Bing BING_API_KEY Yes Yes Yes Yes
Brave BRAVE_API_KEY Yes Yes Yes Yes
DataForSEO DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD Yes No Yes No
SearchAPI SEARCHAPI_API_KEY Yes Yes Yes Yes
ValueSERP VALUESERP_API_KEY Yes Yes Yes Yes
ScrapingDog SCRAPINGDOG_API_KEY Yes Yes Yes No
Bright Data BRIGHTDATA_API_KEY Yes Yes Yes Yes
SearchCans SEARCHCANS_API_KEY Yes No Yes No

Provider Routing

Specify a provider with provider/query format:

// Use a specific provider
results, _ := client.Search(ctx, serp.SearchRequest{Query: "serper/go frameworks"})

// Or just search with the first available
results, _ := client.Search(ctx, serp.SearchRequest{Query: "go frameworks"})

Search Options

results, err := client.Search(ctx, serp.SearchRequest{
    Query:     "go frameworks",
    Num:       20,                    // number of results
    Page:      2,                     // page number
    Country:   "us",                  // country code
    Language:  "en",                  // language code
    Safe:      true,                  // safe search
    Type:      serp.SearchTypeWeb,    // web, images, news, videos
    DateRange: serp.DateRangeMonth,   // day, week, month, year
})

Fallback Routing

Try multiple providers in order. If one fails, the next is attempted:

results, err := client.SearchWithFallback(ctx, serp.SearchRequest{
    Query: "go frameworks",
}, []string{"serper", "brave", "bing"})

Unified Response Format

All providers return the same SearchResponse struct:

type SearchResponse struct {
    Provider       string
    Query          string
    Results        []SearchResult
    TotalResults   int
    SearchTime     float64 // ms
    RelatedSearches []string
    PeopleAlsoAsk  []PeopleAlsoAsk
    KnowledgePanel *KnowledgePanel
    AnswerBox      *AnswerBox
    AiOverview     *AiOverview
}

type SearchResult struct {
    Position      int
    Title         string
    URL           string
    Description   string
    Domain        string
    DatePublished string
    // Image fields
    ImageURL      string
    ImageWidth    int
    ImageHeight   int
    // News fields
    Source        string
    // Video fields
    Duration      string
    Channel       string
}

Configuration

Programmatic
client := serp.New(&serp.Config{
    Serper:      &serp.ProviderConfig{APIKey: "..."},
    Brave:       &serp.ProviderConfig{APIKey: "..."},
    Google:      &serp.ProviderConfig{APIKey: "...", EngineID: "..."},
    DataForSEO:  &serp.DataForSeoConfig{Login: "...", Password: "..."},
    SearchAPI:   &serp.ProviderConfig{APIKey: "..."},
    ValueSERP:   &serp.ProviderConfig{APIKey: "..."},
    ScrapingDog: &serp.ProviderConfig{APIKey: "..."},
    BrightData:  &serp.ProviderConfig{APIKey: "..."},
    SearchCans:  &serp.ProviderConfig{APIKey: "..."},
    Defaults: &serp.SearchDefaults{
        Num:      10,
        Country:  "us",
        Language: "en",
        Safe:     true,
    },
    Aliases: map[string]string{
        "fast":    "serper",
        "default": "brave",
    },
})
Environment Variables
export SERPER_API_KEY=...
export SERPAPI_API_KEY=...
export GOOGLE_CSE_API_KEY=...
export GOOGLE_CSE_ENGINE_ID=...
export BING_API_KEY=...
export BRAVE_API_KEY=...
export DATAFORSEO_LOGIN=...
export DATAFORSEO_PASSWORD=...
export SEARCHAPI_API_KEY=...
export VALUESERP_API_KEY=...
export SCRAPINGDOG_API_KEY=...
export BRIGHTDATA_API_KEY=...
export SEARCHCANS_API_KEY=...

People Also Ask

Available from 8 providers (Serper, SerpAPI, SearchAPI, ValueSERP, DataForSEO, ScrapingDog, Bright Data, SearchCans):

results, _ := client.Search(ctx, serp.SearchRequest{Query: "how to start an LLC"})
for _, paa := range results.PeopleAlsoAsk {
    fmt.Println(paa.Question, paa.Snippet)
}

AI Overview

Fetch Google's AI-generated overview content (requires SearchAPI):

results, _ := client.Search(ctx, serp.SearchRequest{
    Query:             "how to start an LLC",
    IncludeAiOverview: true,
})

if results.AiOverview != nil {
    fmt.Println(results.AiOverview.Markdown)
    for _, ref := range results.AiOverview.References {
        fmt.Printf("  [%d] %s - %s\n", ref.Index, ref.Title, ref.URL)
    }
}

See Also

Package Description
@probeo/anyserp TypeScript version of this package
anyserp-py Python version of this package
anymodel-go Unified LLM router for Go
workflow-go Stage-based pipeline engine for Go

License

MIT

Documentation

Overview

Package anyserp provides a unified SERP API router supporting 11 search providers.

Index

Constants

View Source 
const Version = "0.1.0"

Version is the current library version.

Variables

This section is empty.

Functions

This section is empty.

Types

type AiOverview 

type AiOverview struct {
	Markdown   string                `json:"markdown,omitempty"`
	TextBlocks []AiOverviewTextBlock `json:"textBlocks"`
	References []AiOverviewReference `json:"references"`
	PageToken  string                `json:"pageToken,omitempty"`
}

AiOverview represents an AI-generated overview from search results.

type AiOverviewReference 

type AiOverviewReference struct {
	Index     int    `json:"index"`
	Title     string `json:"title,omitempty"`
	URL       string `json:"url,omitempty"`
	Snippet   string `json:"snippet,omitempty"`
	Date      string `json:"date,omitempty"`
	Source    string `json:"source,omitempty"`
	Thumbnail string `json:"thumbnail,omitempty"`
}

AiOverviewReference represents a source cited in an AI overview.

type AiOverviewTable 

type AiOverviewTable struct {
	Headers []string   `json:"headers"`
	Rows    [][]string `json:"rows"`
}

AiOverviewTable holds tabular data within an AI overview block.

type AiOverviewTextBlock 

type AiOverviewTextBlock struct {
	Type             string                `json:"type"`
	Answer           string                `json:"answer,omitempty"`
	AnswerHighlight  string                `json:"answerHighlight,omitempty"`
	Items            []AiOverviewTextBlock `json:"items,omitempty"`
	Table            *AiOverviewTable      `json:"table,omitempty"`
	Language         string                `json:"language,omitempty"`
	Code             string                `json:"code,omitempty"`
	Video            *AiOverviewVideo      `json:"video,omitempty"`
	ReferenceIndexes []int                 `json:"referenceIndexes,omitempty"`
	Link             string                `json:"link,omitempty"`
	RelatedSearches  []RelatedSearch       `json:"relatedSearches,omitempty"`
}

AiOverviewTextBlock represents a structured block within an AI overview.

type AiOverviewVideo 

type AiOverviewVideo struct {
	Title    string `json:"title,omitempty"`
	Link     string `json:"link,omitempty"`
	Duration string `json:"duration,omitempty"`
	Source   string `json:"source,omitempty"`
	Channel  string `json:"channel,omitempty"`
}

AiOverviewVideo holds video metadata within an AI overview block.

type AnswerBox 

type AnswerBox struct {
	Snippet string `json:"snippet"`
	Title   string `json:"title,omitempty"`
	URL     string `json:"url,omitempty"`
}

AnswerBox represents a featured answer box.

type AnySerp 

type AnySerp struct {
	// contains filtered or unexported fields
}

AnySerp is the main client for searching across multiple providers.

func New 

func New(config *Config) *AnySerp

New creates a new AnySerp client. If config is nil, providers are loaded from environment variables only.

func (*AnySerp) GetRegistry 

func (a *AnySerp) GetRegistry() *Registry

GetRegistry returns the underlying registry for direct adapter access.

func (*AnySerp) Providers 

func (a *AnySerp) Providers() []string

Providers returns the names of all configured providers.

func (*AnySerp) Search 

func (a *AnySerp) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

Search executes a search using the first available provider that supports the requested search type. If the query contains a provider prefix (e.g. "serper/golang"), that provider is used directly.

func (*AnySerp) SearchWithFallback 

func (a *AnySerp) SearchWithFallback(ctx context.Context, request SearchRequest, providers []string) (*SearchResponse, error)

SearchWithFallback tries providers in order, falling back on error.

type AnySerpError 

type AnySerpError struct {
	Code     int
	Message  string
	Metadata map[string]interface{}
}

AnySerpError represents an error returned by a search provider.

func NewAnySerpError 

func NewAnySerpError(code int, message string, metadata map[string]interface{}) *AnySerpError

NewAnySerpError creates a new AnySerpError.

func (*AnySerpError) Error 

func (e *AnySerpError) Error() string

type BingAdapter 

type BingAdapter struct {
	// contains filtered or unexported fields
}

BingAdapter implements SearchAdapter for the Bing Web Search API.

func NewBingAdapter 

func NewBingAdapter(apiKey string, client *http.Client) *BingAdapter

NewBingAdapter creates a new BingAdapter.

func (*BingAdapter) Name 

func (a *BingAdapter) Name() string

func (*BingAdapter) Search 

func (a *BingAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*BingAdapter) SupportsType 

func (a *BingAdapter) SupportsType(_ SearchType) bool

type BraveAdapter 

type BraveAdapter struct {
	// contains filtered or unexported fields
}

BraveAdapter implements SearchAdapter for the Brave Search API.

func NewBraveAdapter 

func NewBraveAdapter(apiKey string, client *http.Client) *BraveAdapter

NewBraveAdapter creates a new BraveAdapter.

func (*BraveAdapter) Name 

func (a *BraveAdapter) Name() string

func (*BraveAdapter) Search 

func (a *BraveAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*BraveAdapter) SupportsType 

func (a *BraveAdapter) SupportsType(_ SearchType) bool

type BrightDataAdapter 

type BrightDataAdapter struct {
	// contains filtered or unexported fields
}

BrightDataAdapter implements SearchAdapter for the Bright Data SERP API.

func NewBrightDataAdapter 

func NewBrightDataAdapter(apiKey string, client *http.Client) *BrightDataAdapter

NewBrightDataAdapter creates a new BrightDataAdapter.

func (*BrightDataAdapter) Name 

func (a *BrightDataAdapter) Name() string

func (*BrightDataAdapter) Search 

func (a *BrightDataAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*BrightDataAdapter) SupportsType 

func (a *BrightDataAdapter) SupportsType(_ SearchType) bool

type Config 

type Config struct {
	Serper      *ProviderConfig
	SerpAPI     *ProviderConfig
	Google      *ProviderConfig
	Bing        *ProviderConfig
	Brave       *ProviderConfig
	DataForSEO  *DataForSeoConfig
	SearchAPI   *ProviderConfig
	ValueSERP   *ProviderConfig
	ScrapingDog *ProviderConfig
	BrightData  *ProviderConfig
	SearchCans  *ProviderConfig
	Defaults    *SearchDefaults
	Aliases     map[string]string
}

Config holds configuration for all search providers.

type DataForSeoAdapter 

type DataForSeoAdapter struct {
	// contains filtered or unexported fields
}

DataForSeoAdapter implements SearchAdapter for the DataForSEO API.

func NewDataForSeoAdapter 

func NewDataForSeoAdapter(login, password string, client *http.Client) *DataForSeoAdapter

NewDataForSeoAdapter creates a new DataForSeoAdapter.

func (*DataForSeoAdapter) Name 

func (a *DataForSeoAdapter) Name() string

func (*DataForSeoAdapter) Search 

func (a *DataForSeoAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*DataForSeoAdapter) SupportsType 

func (a *DataForSeoAdapter) SupportsType(t SearchType) bool

type DataForSeoConfig 

type DataForSeoConfig struct {
	Login    string
	Password string
}

DataForSeoConfig holds credentials for the DataForSEO provider.

type DateRange 

type DateRange string

DateRange specifies a time-based filter for search results. 

const (
	DateRangeDay   DateRange = "day"
	DateRangeWeek  DateRange = "week"
	DateRangeMonth DateRange = "month"
	DateRangeYear  DateRange = "year"
)

type GoogleAdapter 

type GoogleAdapter struct {
	// contains filtered or unexported fields
}

GoogleAdapter implements SearchAdapter for Google Custom Search Engine.

func NewGoogleAdapter 

func NewGoogleAdapter(apiKey, engineID string, client *http.Client) *GoogleAdapter

NewGoogleAdapter creates a new GoogleAdapter.

func (*GoogleAdapter) Name 

func (a *GoogleAdapter) Name() string

func (*GoogleAdapter) Search 

func (a *GoogleAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*GoogleAdapter) SupportsType 

func (a *GoogleAdapter) SupportsType(t SearchType) bool

type KnowledgePanel 

type KnowledgePanel struct {
	Title       string            `json:"title"`
	Type        string            `json:"type,omitempty"`
	Description string            `json:"description,omitempty"`
	Source      string            `json:"source,omitempty"`
	SourceURL   string            `json:"sourceUrl,omitempty"`
	Attributes  map[string]string `json:"attributes,omitempty"`
	ImageURL    string            `json:"imageUrl,omitempty"`
}

KnowledgePanel represents a knowledge graph panel.

type PeopleAlsoAsk 

type PeopleAlsoAsk struct {
	Question string `json:"question"`
	Snippet  string `json:"snippet,omitempty"`
	Title    string `json:"title,omitempty"`
	URL      string `json:"url,omitempty"`
}

PeopleAlsoAsk represents a "People Also Ask" item.

type ProviderConfig 

type ProviderConfig struct {
	APIKey   string
	EngineID string // Google CSE only
}

ProviderConfig holds API credentials for a search provider.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages search provider adapters.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new empty registry.

func (*Registry) All 

func (r *Registry) All() []SearchAdapter

All returns all registered adapters in registration order.

func (*Registry) Get 

func (r *Registry) Get(name string) SearchAdapter

Get returns an adapter by name.

func (*Registry) Names 

func (r *Registry) Names() []string

Names returns the names of all registered adapters in registration order.

func (*Registry) Register 

func (r *Registry) Register(name string, adapter SearchAdapter)

Register adds an adapter to the registry.

type RelatedSearch 

type RelatedSearch struct {
	Query string `json:"query"`
	Link  string `json:"link,omitempty"`
}

RelatedSearch represents a related search suggestion.

type ScrapingDogAdapter 

type ScrapingDogAdapter struct {
	// contains filtered or unexported fields
}

ScrapingDogAdapter implements SearchAdapter for the ScrapingDog API.

func NewScrapingDogAdapter 

func NewScrapingDogAdapter(apiKey string, client *http.Client) *ScrapingDogAdapter

NewScrapingDogAdapter creates a new ScrapingDogAdapter.

func (*ScrapingDogAdapter) Name 

func (a *ScrapingDogAdapter) Name() string

func (*ScrapingDogAdapter) Search 

func (a *ScrapingDogAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*ScrapingDogAdapter) SupportsType 

func (a *ScrapingDogAdapter) SupportsType(t SearchType) bool

type SearchAPIAdapter 

type SearchAPIAdapter struct {
	// contains filtered or unexported fields
}

SearchAPIAdapter implements SearchAdapter for the SearchAPI.io service.

func NewSearchAPIAdapter 

func NewSearchAPIAdapter(apiKey string, client *http.Client) *SearchAPIAdapter

NewSearchAPIAdapter creates a new SearchAPIAdapter.

func (*SearchAPIAdapter) Name 

func (a *SearchAPIAdapter) Name() string

func (*SearchAPIAdapter) Search 

func (a *SearchAPIAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*SearchAPIAdapter) SupportsType 

func (a *SearchAPIAdapter) SupportsType(_ SearchType) bool

type SearchAdapter 

type SearchAdapter interface {
	Name() string
	Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)
	SupportsType(searchType SearchType) bool
}

SearchAdapter defines the interface that all search providers implement.

type SearchCansAdapter 

type SearchCansAdapter struct {
	// contains filtered or unexported fields
}

SearchCansAdapter implements SearchAdapter for the SearchCans API.

func NewSearchCansAdapter 

func NewSearchCansAdapter(apiKey string, client *http.Client) *SearchCansAdapter

NewSearchCansAdapter creates a new SearchCansAdapter.

func (*SearchCansAdapter) Name 

func (a *SearchCansAdapter) Name() string

func (*SearchCansAdapter) Search 

func (a *SearchCansAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*SearchCansAdapter) SupportsType 

func (a *SearchCansAdapter) SupportsType(t SearchType) bool

type SearchDefaults 

type SearchDefaults struct {
	Num      int
	Country  string
	Language string
	Safe     bool
}

SearchDefaults holds default values applied to all search requests.

type SearchRequest 

type SearchRequest struct {
	Query             string     `json:"query"`
	Num               int        `json:"num,omitempty"`
	Page              int        `json:"page,omitempty"`
	Country           string     `json:"country,omitempty"`
	Language          string     `json:"language,omitempty"`
	Safe              bool       `json:"safe,omitempty"`
	Type              SearchType `json:"type,omitempty"`
	DateRange         DateRange  `json:"dateRange,omitempty"`
	IncludeAiOverview bool       `json:"includeAiOverview,omitempty"`
}

SearchRequest holds parameters for a search query.

type SearchResponse 

type SearchResponse struct {
	Provider        string          `json:"provider"`
	Query           string          `json:"query"`
	Results         []SearchResult  `json:"results"`
	TotalResults    int             `json:"totalResults,omitempty"`
	SearchTime      float64         `json:"searchTime,omitempty"`
	RelatedSearches []string        `json:"relatedSearches,omitempty"`
	PeopleAlsoAsk   []PeopleAlsoAsk `json:"peopleAlsoAsk,omitempty"`
	KnowledgePanel  *KnowledgePanel `json:"knowledgePanel,omitempty"`
	AnswerBox       *AnswerBox      `json:"answerBox,omitempty"`
	AiOverview      *AiOverview     `json:"aiOverview,omitempty"`
}

SearchResponse holds the results of a search query.

type SearchResult 

type SearchResult struct {
	Position      int    `json:"position"`
	Title         string `json:"title"`
	URL           string `json:"url"`
	Description   string `json:"description"`
	Domain        string `json:"domain,omitempty"`
	DatePublished string `json:"datePublished,omitempty"`
	Thumbnail     string `json:"thumbnail,omitempty"`
	// Image-specific
	ImageURL    string `json:"imageUrl,omitempty"`
	ImageWidth  int    `json:"imageWidth,omitempty"`
	ImageHeight int    `json:"imageHeight,omitempty"`
	// News-specific
	Source string `json:"source,omitempty"`
	// Video-specific
	Duration string `json:"duration,omitempty"`
	Channel  string `json:"channel,omitempty"`
}

SearchResult represents a single search result.

type SearchType 

type SearchType string

SearchType specifies the kind of search to perform. 

const (
	SearchTypeWeb    SearchType = "web"
	SearchTypeImages SearchType = "images"
	SearchTypeNews   SearchType = "news"
	SearchTypeVideos SearchType = "videos"
)

type SerpAPIAdapter 

type SerpAPIAdapter struct {
	// contains filtered or unexported fields
}

SerpAPIAdapter implements SearchAdapter for the SerpAPI service.

func NewSerpAPIAdapter 

func NewSerpAPIAdapter(apiKey string, client *http.Client) *SerpAPIAdapter

NewSerpAPIAdapter creates a new SerpAPIAdapter.

func (*SerpAPIAdapter) Name 

func (a *SerpAPIAdapter) Name() string

func (*SerpAPIAdapter) Search 

func (a *SerpAPIAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*SerpAPIAdapter) SupportsType 

func (a *SerpAPIAdapter) SupportsType(_ SearchType) bool

type SerperAdapter 

type SerperAdapter struct {
	// contains filtered or unexported fields
}

SerperAdapter implements SearchAdapter for the Serper API.

func NewSerperAdapter 

func NewSerperAdapter(apiKey string, client *http.Client) *SerperAdapter

NewSerperAdapter creates a new SerperAdapter.

func (*SerperAdapter) Name 

func (a *SerperAdapter) Name() string

func (*SerperAdapter) Search 

func (a *SerperAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*SerperAdapter) SupportsType 

func (a *SerperAdapter) SupportsType(_ SearchType) bool

type ValueSerpAdapter 

type ValueSerpAdapter struct {
	// contains filtered or unexported fields
}

ValueSerpAdapter implements SearchAdapter for the ValueSERP API.

func NewValueSerpAdapter 

func NewValueSerpAdapter(apiKey string, client *http.Client) *ValueSerpAdapter

NewValueSerpAdapter creates a new ValueSerpAdapter.

func (*ValueSerpAdapter) Name 

func (a *ValueSerpAdapter) Name() string

func (*ValueSerpAdapter) Search 

func (a *ValueSerpAdapter) Search(ctx context.Context, request SearchRequest) (*SearchResponse, error)

func (*ValueSerpAdapter) SupportsType 

func (a *ValueSerpAdapter) SupportsType(_ SearchType) bool

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.