# Go SDK

The official Go client for the Synthient API: IP and domain lookups, account details, real-time feed streams, and Parquet exports.

> **Note**: The generated reference for every package, type, and method is on [pkg.go.dev](https://pkg.go.dev/github.com/synthient/synthient-go). These pages cover the same surface with examples. The source and runnable programs are at [github.com/synthient/synthient-go](https://github.com/synthient/synthient-go).

## Getting started

### 1. Install

```bash
go get github.com/synthient/synthient-go
```

Requires Go 1.26 or later. The package is named `synthient`. The [gRPC schema](https://docs.synthient.com/sdks/go/grpc-schema) fetcher lives in a separate package in the same module, `github.com/synthient/synthient-go/grpcschema`. The first time you import it, run `go mod tidy` to add its gRPC dependencies.

### 2. Make your first lookup

This program creates a client with the API key in `SYNTHIENT_API_KEY` and looks up one address. Each lookup costs one credit.

```go
package main

import (
	"context"
	"fmt"
	"log"
	"net/netip"
	"os"

	"github.com/synthient/synthient-go"
)

func main() {
	client, err := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	info, err := client.LookupIP(context.Background(), netip.MustParseAddr("8.8.8.8"))
	if err != nil {
		log.Fatal(err)
	}
	if info.Network != nil {
		fmt.Println(info.Network.ISP, info.Network.Type)
	}
	if info.Intelligence != nil {
		fmt.Println(info.Intelligence.RiskScore, info.Intelligence.Categories)
	}
}
```

`IPInfo.Network`, `IPInfo.Location`, and `IPInfo.Intelligence` are `nil` when the API has no data for that section, so check them before reading their fields.

### 3. Check your credits

`Account` returns the account that owns the API key, including its scopes and remaining lookup credits. It costs no credits.

```go
account, err := client.Account(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(account.Email, account.Organization.Name, account.Scopes)
fmt.Println(account.LookupQuota.Credits, "credits, resetting in", account.LookupQuota.ResetsIn, "seconds")
```

### 4. Handle errors

A request that fails with a non-success HTTP status returns an `*APIError`. Inspect it with `errors.AsType`:

```go
_, err := client.LookupIP(ctx, netip.MustParseAddr("8.8.8.8"))
apiErr, ok := errors.AsType[*synthient.APIError](err)
if ok {
	switch {
	case apiErr.StatusCode == http.StatusPaymentRequired:
		fmt.Println("out of lookup credits")
	case apiErr.StatusCode == http.StatusTooManyRequests && apiErr.RetryAfter > 0:
		fmt.Println("rate limited, retry after", apiErr.RetryAfter)
	case apiErr.StatusCode == http.StatusTooManyRequests:
		fmt.Println("monthly request budget spent")
	default:
		fmt.Println("request", apiErr.RequestID, "failed:", cmp.Or(apiErr.Detail, apiErr.Title))
	}
}
```

### 5. Keep going

- [Client](https://docs.synthient.com/sdks/go/client): create and configure the client, and read the metadata of every API response.
- [Lookups](https://docs.synthient.com/sdks/go/lookups): look up IP addresses and domains, and check your account and the API's health.
- [Feeds](https://docs.synthient.com/sdks/go/feeds): stream each feed's real-time events and download its hourly and daily Parquet exports.
- [Errors and retries](https://docs.synthient.com/sdks/go/errors): how failed requests are reported, and which requests are retried.
- [Types](https://docs.synthient.com/sdks/go/types): the fields of every response and event type, and the enumerations they use.
- [gRPC schema](https://docs.synthient.com/sdks/go/grpc-schema): fetch the protobuf schema of the Synthient gRPC API.