Go SDK

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

Getting started

1. Install

go get github.com/synthient/synthient-go

Requires Go 1.26 or later. The package is named synthient. The 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.

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.

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:

_, 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: create and configure the client, and read the metadata of every API response.
• Lookups: look up IP addresses and domains, and check your account and the API's health.
• Feeds: stream each feed's real-time events and download its hourly and daily Parquet exports.
• Errors and retries: how failed requests are reported, and which requests are retried.
• Types: the fields of every response and event type, and the enumerations they use.
• gRPC schema: fetch the protobuf schema of the Synthient gRPC API.