anyserp

package module
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: May 2, 2026 License: MIT Imports: 12 Imported by: 0

README

anyserp-go

Go Reference CI License

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

Why anyserp?

One SDK, 11 SERP providers. Switch providers without changing code. Every provider returns the same unified response struct, so your application logic stays clean regardless of which provider handles the request. Your API keys, your infrastructure, zero routing fees. Built-in fallback routing means if one provider fails, the next is tried automatically.

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

Support

If anyserp is useful to you, consider giving it a star. It helps others discover the project.

License

MIT

Documentation

Overview

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

Index

Constants

View Source 
const Version = "0.2.2"

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(t 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(t 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(t 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 Coordinates added in v0.2.0 

type Coordinates struct {
	Lat float64 `json:"lat"`
	Lng float64 `json:"lng"`
}

Coordinates holds a geographic latitude/longitude pair.

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(t 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"`
	// Places-specific
	Address     string       `json:"address,omitempty"`
	Phone       string       `json:"phone,omitempty"`
	Rating      float64      `json:"rating,omitempty"`
	ReviewCount int          `json:"reviewCount,omitempty"`
	PlaceType   string       `json:"placeType,omitempty"`
	Hours       string       `json:"hours,omitempty"`
	Coordinates *Coordinates `json:"coordinates,omitempty"`
	Kgmid       string       `json:"kgmid,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"
	SearchTypePlaces SearchType = "places"
)

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(t 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(t 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(t SearchType) bool

Source Files

View all Source files

Directories

Path Synopsis

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.