# searchSDK for Go

Go 1.23+. 14 normalized web-search adapters and 493 retained native bindings across 13 providers; gateway client.

Canonical: https://searchsdk.dev/docs/sdks/go
Markdown: https://searchsdk.dev/docs/sdks/go.md

<a id="install"></a>

## Install from source

Package: `github.com/Belweave/searchSDK/packages/go`, version `0.1.0-alpha.1`. This is an alpha source/local-artifact installation. No public registry release or release tag is assumed.

**Get the source**

```bash
git clone https://github.com/Belweave/searchSDK.git
cd searchSDK
# Record this revision with your application's dependency lock.
git rev-parse HEAD
```

**Build or install the local package**

```bash
# In your application's existing Go module, for a local checkout:
go mod edit -require=github.com/Belweave/searchSDK/packages/go@v0.0.0
go mod edit -replace=github.com/Belweave/searchSDK/packages/go=/absolute/path/searchSDK/packages/go
go mod tidy
```

Add the import shown below before go mod tidy. This local replace is a development installation, not a published module version. Future release tags must use the packages/go/v prefix. The module uses only the standard library.

<a id="first-search"></a>

## Make a server-side search

Set provider keys in your application's server environment or secret store. The example below makes a real provider request when invoked and can incur charges. Use the package's fixture consumer for a key-free check.

**main.go**

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"
    searchsdk "github.com/Belweave/searchSDK/packages/go"
)

func main() {
    provider, err := searchsdk.NewAdapter("exa", searchsdk.AdapterOptions{
        APIKey: os.Getenv("EXA_API_KEY"),
    })
    if err != nil { log.Fatal(err) }
    search, err := searchsdk.New(searchsdk.Config{Provider: provider})
    if err != nil { log.Fatal(err) }
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    response, err := search.Search(ctx, searchsdk.Request{
        Query: "SQLite write concurrency", Limit: 3,
    })
    if err != nil { log.Fatal(err) }
    fmt.Println(response.Results)
}
```

Set EXA_API_KEY on your server and run go run . from the application module. Keep context cancellation tied to the incoming request in a service.

<a id="scope"></a>

## Supported surface and limits

14 normalized web-search adapters and 493 retained native bindings across 13 providers; gateway client.

- No cache, deduplication or automatic side-effect recovery.
- Custom providers and RoundTrippers must honor context.Context; the SDK does not hide uncooperative work in detached workers.

Preserve result order, provider-native scores and source provenance. Unknown usage is not zero cost. Cancellation and deadlines cannot undo a request already accepted by a remote system or guarantee exactly-once effects.

<a id="verify"></a>

## Verify without provider keys

**Repository checkout · local checks**

```bash
go -C packages/go test -race -p 2 ./...
go -C packages/go vet -p 2 ./...
python3 -B packages/go/internal/verify_consumer.py
```

Go 1.23 and 1.27 race checks and an external consumer resolving a local module-proxy ZIP without replace.

These are deterministic contract and artifact checks. They do not establish live-provider or account-entitlement verification. Read the package README for precise commands, dependencies and runtime coverage.

<a id="next"></a>

## Continue in your language

- [Go package reference](https://github.com/Belweave/searchSDK/tree/main/packages/go#readme): Complete API, errors, streaming, packaging and platform boundaries.
- [Compare SDKs](https://searchsdk.dev/docs/sdks)
- [Choose a provider](https://searchsdk.dev/docs/providers)