synthient

package module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 18, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Image README

go-synthient

godoc go.mod version report card

synthient sdk for golang

Installation

You can add this sdk to your project with the following terminal command:

go get -u github.com/synthient/go-synthient
Creating a synthient.Client

When using this SDK all requests are made with a synthient.Client. You can create this struct manually or with the synthient.NewClient function:

package main

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

func main() {
    client := synthient.NewClient("SECRET TOKEN")
}
Getting IP data

One of the first things you can do with your new client is get IP data. Here is an example of getting IP data for a given IP using client.GetIP(...):

package main

import (
	"fmt"
	"log"
	"os"

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

func main() {
	client := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
	resp, err := client.GetIP("213.149.183.127", nil)
	if err != nil {
		log.Fatalf("failed to get ip address: %s", err)
	}
	fmt.Println(resp.IP)
}

client.GetIP returns a synthient.IP value, along with the error if there is one, of course.

Anonymizer Feed Data
Streaming

You can stream the feed using client.StreamAnonymizersFeed(...):

package main

import (
	"io"
	"log"
	"os"

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

func main() {
	client := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
	stream, err := client.StreamAnonymizersFeed(synthient.AnonymizersQuery{
		Provider:     "BIRDPROXIES",
		Type:         "RESIDENTIAL_PROXY",
		LastObserved: "7D",
		Format:       "CSV",
		CountryCode:  "US",
		Full:         false,
		Order:        "desc",
	}, nil)
	if err != nil {
		log.Fatalf("failed to stream feed: %s", err)
	}
	defer func() { _ = stream.Close() }() // important! make sure to close stream

	_, err = io.Copy(os.Stdout, stream)
	if err != nil {
		log.Fatalf("failed to read stream: %s", err)
	}
}
Downloading

Using client.DownloadAnonymizersFeed(...) you can easily stream a feed to a file. This will save it to a file called feed.csv in this example:

package main

import (
	"fmt"
	"log"
	"os"

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

func main() {
	client := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
	n, err := client.DownloadAnonymizersFeed(synthient.AnonymizersQuery{
		Provider:     "BIRDPROXIES",
		Type:         "RESIDENTIAL_PROXY",
		LastObserved: "7D",
		Format:       "CSV",
		CountryCode:  "US",
		Full:         false,
		Order:        "desc",
	}, "feed.csv", nil)
	if err != nil {
		log.Fatalf("failed to download feed: %s", err)
	}

	fmt.Println(n, "bytes downloaded")
}

Client Customization

The synthient.Client can be customized to use a self-hosted endpoint for example. Here is an example:

package main

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

func main() {
    client := synthient.NewClient("SECRET TOKEN")
    client.BaseAPI.Host = "synthient.myserver.com"
}

Image Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNoToken    = errors.New("no token provided for client")
	ErrFileExists = errors.New("file already exists")
)
View Source 
var (
	ErrBadRequest           = errors.New("invalid input parameters")
	ErrUnauthorized         = errors.New("no api key was provided or the key is invalid")
	ErrPaymentRequired      = errors.New("credits have run out")
	ErrInternalServerError  = errors.New("unexpected error occurred")
	ErrUnexpectedStatusCode = errors.New("returned status code did not match expected status code")
)

Functions

This section is empty.

Types

type AnonymizersQuery 

type AnonymizersQuery struct {
	Provider     string
	Type         string
	LastObserved string
	CountryCode  string
	Format       string
	Full         bool
	Order        string
}

AnonymizersQuery defines the set of filters and output options used when requesting the Synthient anonymizers feed.

Fields are translated into HTTP query parameters by StreamAnonymizersFeed / DownloadAnonymizersFeed. Leave string fields empty to omit that filter.

Typical values include:

  • Provider: feed source/provider identifier (e.g. "BIRDPROXIES").
  • Type: anonymizer category/type (e.g. "RESIDENTIAL_PROXY").
  • LastObserved: recency window for when an entry was last observed (API-specific, e.g. "7D").
  • CountryCode: ISO 3166-1 alpha-2 country code (e.g. "US").
  • Format: output format (e.g. "CSV").
  • Full: when true, request the “full” dataset if supported by the API.
  • Order: sort order.

type Client 

type Client struct {
	HttpClient *http.Client
	Token      string
	BaseAPI    url.URL
	BaseFeeds  url.URL
}

Client is a Synthient API client.

It holds the HTTP transport and configuration required to make API and feed requests.

Fields:

  • HttpClient is the underlying HTTP client used for all requests. If nil, the package may fall back to http.DefaultClient (depending on request helpers).
  • Token is the API token used for authentication.
  • BaseAPI is the base URL for JSON API endpoints (e.g. lookups).
  • BaseFeeds is the base URL for feed endpoints that may return large, streamable payloads (e.g. CSV feeds).

func NewClient 

func NewClient(token string) Client

NewClient constructs a Client configured for the Synthient v3 API.

The returned client is initialized with:

  • a new *http.Client as the underlying transport,
  • the provided token for authentication, and
  • default base URLs for the JSON API (BaseAPI) and feeds service (BaseFeeds).

If you need custom timeouts, proxies, or transports, modify c.HttpClient after construction. If Synthient endpoints differ for your environment, you may also override BaseAPI and/or BaseFeeds.

Example: 

c := synthient.NewClient(os.Getenv("SYNTHIENT_API_KEY"))
c.HttpClient.Timeout = 30 * time.Second

func (*Client) DownloadAnonymizersFeed 

func (client *Client) DownloadAnonymizersFeed(
	query AnonymizersQuery,
	filepath string,
	options *RequestOptions,
) (int64, error)

DownloadAnonymizersFeed downloads the Synthient “anonymizers” feed to a file.

This is a convenience wrapper around StreamAnonymizersFeed that streams the HTTP response body directly to disk (via io.Copy) to avoid buffering the entire feed in memory. It returns the number of bytes written.

filepath must not already exist. If it does, DownloadAnonymizersFeed returns ErrFileExists (wrapped) and does not modify the filesystem. On success, the file is created, written, and fsynced (file.Sync) before returning.

Request behavior (timeouts, headers, etc.) can be customized via options. The query is interpreted the same way as StreamAnonymizersFeed.

Example: 

n, err := client.DownloadAnonymizersFeed(synthient.AnonymizersQuery{
	Provider:     "BIRDPROXIES",
	Type:         "RESIDENTIAL_PROXY",
	LastObserved: "7D",
	Format:       "CSV",
	CountryCode:  "US",
	Full:         false,
	Order:        "desc",
}, "anonymizers.csv", nil)
if err != nil {
	log.Fatal(err)
}
log.Printf("wrote %d bytes\n", n)

func (*Client) GetIP 

func (client *Client) GetIP(ip string, options *RequestOptions) (IP, error)

GetIP looks up enrichment data for a single IP address.

It performs an HTTP GET request to the Synthient IP lookup endpoint and unmarshals the JSON response into an IP value. The request is expected to return http.StatusOK; non-OK responses are returned as errors.

options can be used to customize request behavior (timeouts, headers, etc.).

Example: 

info, err := client.GetIP("8.8.8.8", nil)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", info)

func (*Client) StreamAnonymizersFeed added in v0.1.0 

func (client *Client) StreamAnonymizersFeed(
	query AnonymizersQuery,
	options *RequestOptions,
) (io.ReadCloser, error)

StreamAnonymizersFeed starts a streaming HTTP GET request for the Synthient “anonymizers” feed and returns the response body as an io.ReadCloser.

The returned reader contains the raw feed payload (for example, CSV when query.Format is "CSV"). Callers MUST ALWAYS close the returned ReadCloser. For large feeds, prefer streaming consumption (io.Copy, bufio.Scanner, or a CSV reader) instead of reading the entire body into memory.

Query fields are translated into request parameters:

  • Provider -> provider
  • Type -> type
  • LastObserved -> last_observed
  • CountryCode -> country_code
  • Full -> full
  • Format -> format
  • Order -> order

Request behavior (timeouts, headers, etc.) can be customized via options. The request is expected to return http.StatusOK; non-OK responses are returned as errors.

Example: 

stream, err := client.StreamAnonymizersFeed(synthient.AnonymizersQuery{
	Provider:     "BIRDPROXIES",
	Type:         "RESIDENTIAL_PROXY",
	LastObserved: "7D",
	Format:       "CSV",
	CountryCode:  "US",
	Full:         false,
	Order:        "desc",
}, nil)
if err != nil {
	log.Fatal(err)
}
defer stream.Close()

type IP 

type IP struct {
	IP      string `json:"ip"`
	Network struct {
		Asn        int    `json:"asn"`
		Isp        string `json:"isp"`
		Type       string `json:"type"`
		Org        string `json:"org"`
		AbuseEmail string `json:"abuse_email"`
		AbusePhone string `json:"abuse_phone"`
		Domain     string `json:"domain"`
	} `json:"network"`
	Location struct {
		Country   string  `json:"country"`
		State     string  `json:"state"`
		City      string  `json:"city"`
		Timezone  string  `json:"timezone"`
		Longitude float64 `json:"longitude"`
		Latitude  float64 `json:"latitude"`
		GeoHash   string  `json:"geo_hash"`
	} `json:"location"`
	IPData struct {
		Devices []struct {
			OS      string `json:"os"`
			Version string `json:"version"`
		} `json:"devices"`
		DeviceCount int      `json:"device_count"`
		Behavior    []string `json:"behavior"`
		Categories  []string `json:"categories"`
		Enriched    []struct {
			Provider string `json:"provider"`
			Type     string `json:"type"`
			LastSeen string `json:"last_seen"`
		} `json:"enriched"`
		IPRisk int `json:"ip_risk"`
	} `json:"ip_data"`
}

IP represents the JSON response returned by the Synthient IP lookup endpoint.

It groups data into three major sections:

  • Network: ASN/ISP and ownership/abuse contacts for the IP’s network.
  • Location: coarse geolocation attributes associated with the IP.
  • IPData: device/behavior/category/enrichment signals and an overall risk score.

Fields and nested structs map 1:1 to the API’s JSON payload via struct tags. Note that values (especially geolocation and “risk”) are provider-derived and may be approximate.

Commonly used fields include IP.IP, Network.Asn/Network.Isp, Location.Country, and IPData.IPRisk.

type RequestOptions 

type RequestOptions struct {
	Context context.Context
}

RequestOptions configures optional per-request behavior for client calls.

It is passed to request helpers and API methods to override defaults without changing the Client itself. When Context is non-nil, it is used for request cancellation, deadlines, and timeouts. If Context is nil, the request uses context.Background() (or the client/request default).

Image Source Files

View all Source files

Image Directories

Path Synopsis
_examples
feeds/download command
feeds/stream command
ip command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.