Go SDK

The official Synthient client library for Go. It covers the same surfaces documented across these docs: IP and domain lookups, account details, Parquet snapshot feeds, real-time firehose and Helios streams, and gRPC schema introspection.

It's open source at github.com/synthient/go-synthient, with full reference docs on pkg.go.dev.

Install

go get -u github.com/synthient/go-synthient/v2

Requires Go 1.25 or later. Real-time streams are built on iter.Seq2, available since Go 1.23.

Getting started

Every request goes through a synthient.Client. Create one with your API key:

client := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))

Each method takes a trailing *synthient.RequestOptions. Pass nil for the defaults, or supply a context to control cancellation and timeouts:

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
opts := &synthient.RequestOptions{Context: ctx}

Lookups

GetIP enriches a single address, GetIPs batches many into one request, and GetDomain returns Helios traffic statistics for a domain.

ip, err := client.GetIP("213.149.183.127", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(ip.Intelligence.RiskScore, ip.Network.Isp, ip.Location.Country)

GetAccount returns the profile and quota details for the authenticated key:

account, err := client.GetAccount(nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(account.Organization.Name, account.LookupQuota.Credits)

Snapshot feeds

FeedSnapshots pages through the available daily and hourly snapshots, newest first. FeedSnapshotMeta returns the checksum, row count, size, and Parquet schema for one of them; date accepts latest, YYYY-MM-DD, or YYYY-MM-DD/HH.

meta, err := client.FeedSnapshotMeta("proxies", "latest", nil)
if err != nil {
    log.Fatal(err)
}
fmt.Println(meta.Rows, meta.Checksum)

DownloadFeedSnapshot follows the API's redirect and hands back a streaming reader for the Parquet file, which the caller closes. Pass a non-nil hour pointer (0–23) to address a specific hourly snapshot in the current UTC day.

r, err := client.DownloadFeedSnapshot("proxies", "latest", nil, nil)
if err != nil {
    log.Fatal(err)
}
defer r.Close()

Per-feed wrappers take the same (date, hour, filename, opts) arguments with the stream pre-filled: DownloadProxy, DownloadAnonymizer, DownloadTorrent, DownloadHeliosHTTP, and DownloadHeliosTLS. Give them a non-empty filename to write straight to disk.

_, err := client.DownloadHeliosTLS("latest", nil, "helios-tls.parquet", nil)

See Feeds for the full snapshot catalog and schemas.

Streams

Every stream method returns an iter.Seq2 that yields one event per NDJSON line. Break out of the loop or cancel the context to stop.

for event, err := range client.StreamProxy(nil) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(event.IP, event.Provider, event.CountryCode)
}

Stream payloads match the Firehose and Helios documentation field for field.

gRPC schema

GRPCSchema pulls protobuf file descriptors from grpc.synthient.com:443 over server reflection. Pass nil to resolve every service, or name the symbols you want.

result, err := client.GRPCSchema(ctx, nil)
if err != nil {
    log.Fatal(err)
}
for _, svc := range result.Symbols {
    fmt.Println(svc)
}

ExplainGRPCError turns transport failures into human-readable messages, and NormalizeGRPCEndpoint handles custom endpoint strings. More detail is on the gRPC page.

Client customization

Point the client at a different endpoint, or replace the HTTP client to control timeouts and proxies:

client.BaseAPI.Host = "synthient.myserver.com"
client.HttpClient = &http.Client{Timeout: 30 * time.Second}