https://github.com/solarhell/go-tavily
A thin, type-safe Go client for the Tavily API
https://github.com/solarhell/go-tavily
api-client go golang sdk search-api tavily tavily-api web-search
Last synced: 4 months ago
JSON representation
A thin, type-safe Go client for the Tavily API
- Host: GitHub
- URL: https://github.com/solarhell/go-tavily
- Owner: solarhell
- License: mit
- Created: 2026-03-05T03:19:26.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-12T06:05:54.000Z (4 months ago)
- Last Synced: 2026-03-12T12:25:34.035Z (4 months ago)
- Topics: api-client, go, golang, sdk, search-api, tavily, tavily-api, web-search
- Language: Go
- Size: 36.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Go Tavily Client
[](https://golang.org/dl/)
[](https://goreportcard.com/report/github.com/solarhell/go-tavily)
[](https://pkg.go.dev/github.com/solarhell/go-tavily)
[](https://coderabbit.ai)
English | [δΈζ](README_zh.md)
A thin, type-safe Go client for the [Tavily API](https://docs.tavily.com). Built for Go 1.26+.
## Installation
```bash
go get github.com/solarhell/go-tavily
```
## Quick Start
```go
client := tavily.New("tvly-your-api-key")
resp, err := client.Search(ctx, &tavily.SearchParams{
Query: "Go programming language",
})
```
## Search
```go
answerMode := tavily.IncludeAnswerAdvanced
resp, err := client.Search(ctx, &tavily.SearchParams{
Query: "AI news",
SearchDepth: tavily.SearchDepthAdvanced,
Topic: tavily.TopicNews,
TimeRange: tavily.TimeRangeWeek,
MaxResults: 10,
IncludeAnswer: &answerMode,
})
```
Zero-value fields are omitted from the request β the API uses its own server-side defaults.
## Country Filter
Use an ISO 3166-1 alpha-2 country code to boost search results from a specific country. The country filter is only available when `topic` is `general` (or unset). Country codes are case-insensitive.
```go
resp, err := client.Search(ctx, &tavily.SearchParams{
Query: "latest tech news",
Country: "US",
})
```
> **Note:** Tavily supports ~160 countries. Unsupported country codes will be rejected at call time.
> Supported country code mapping file: [`country.go`](./country.go).
> Example codes: `US`/`us`, `CN`/`cn`, `JP`/`jp`.
> The SDK handles country codes case-insensitively.
> Current SDK mapping is implemented as of **2026-03-05**.
## Extract
```go
resp, err := client.Extract(ctx, &tavily.ExtractParams{
URLs: []string{"https://example.com"},
Format: tavily.FormatMarkdown,
})
```
## Client Options
```go
client := tavily.New("tvly-your-api-key",
tavily.WithBaseURL("https://custom.api.com"),
tavily.WithHTTPClient(&http.Client{Timeout: 45 * time.Second}),
)
```
If the API key is empty, it reads from the `TAVILY_API_KEY` environment variable.
## Error Handling
```go
resp, err := client.Search(ctx, &tavily.SearchParams{Query: "test"})
if err != nil {
var apiErr *tavily.APIError
if errors.As(err, &apiErr) {
switch {
case apiErr.IsUnauthorized():
// invalid API key (401)
case apiErr.IsRateLimit():
// rate limited (429)
case apiErr.IsPlanLimitExceeded():
// plan usage limit (432)
case apiErr.IsPayGoLimitExceeded():
// pay-as-you-go limit (433)
case apiErr.IsBadRequest():
// invalid parameters (400)
}
}
}
```
## Testing
```bash
go test -v -race ./...
```
## Links
- [Tavily API Documentation](https://docs.tavily.com)