soax

package
v0.0.8 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2025 License: Apache-2.0 Imports: 13 Imported by: 0

README

SOAX Client

SOAX is a provider of Residential, Mobile, and Datacenter proxy services. This document describes how to use its API.

Key Concepts

  • Account: User account, tied to the email you use to log in. You need to have your identity verified in order to enable the account.
  • API Key: Unique key tied to your account, used in the API calls. You can find it under USER > Profile. Keep it secret.
  • Package: Proxy packages give you access to the proxy service. Packages can be of various types based on where the proxy lives, including Residential, Mobile, Datacenter. The service website has a list of available locations.
  • Package ID: A unique 6-digit identifier shown on each package in the package list UI. Used in proxy requests.
  • Package Key: Unique key tied to a specific package you have purchased. It shows up as "Password" in the web UI, under "QUICK ACCESS". Used in the REST API and proxy requests. Keep it secret.

SOAX Proxy API

SOAX supports both HTTP CONNECT proxies and SOCKS5 proxies. In both cases it uses basic authentication ("username:password"), where the password is the Package Key, and the username is a configuration string specifying the parameters of the connection.

Proxy string:

package-<package_id>[-country-<country_iso>[-isp-<isp_name>][-region-<region_name>[-city-<city_name>]]][-sessionid-<session_id>-[sessionlength-<session_length>]]:<package_key>@proxy.soax.com:5000

The isp_name,region_name and city_name must be ones returned by the REST API. They may contain spaces, which should be replaced with + (e.g. new+york).

For more details, see Sticky sessions.

It's helpful to use https://checker.soax.com/api/ipinfo to verify the location information of the proxy.

Here is an example of using SOCKS5 to connect from Germany:

$ curl --proxy "socks5h://package-${SOAX_PACKAGE_ID}-country-de-isp-o2+deutschland:${SOAX_PACKAGE_KEY}@proxy.soax.com:5000" https://checker.soax.com/api/ipinfo

{"status":true,"reason":"","data":{"carrier":"O2 Deutschland","city":"Leipzig","country_code":"DE","country_name":"Germany","ip":"<redacted>","isp":"O2 Deutschland","region":"Saxony"}}

Here is the same request using HTTP CONNECT:

$ curl --proxy "https://package-${SOAX_PACKAGE_ID}-country-de-isp-o2+deutschland:${SOAX_PACKAGE_KEY}@proxy.soax.com:5000" https://checker.soax.com/api/ipinfo

{"status":true,"reason":"","data":{"carrier":"O2 Deutschland","city":"Wuppertal","country_code":"DE","country_name":"Germany","ip":"176.1.206.77","isp":"O2 Deutschland","region":"North Rhine-Westphalia"}}

HTTP CONNECT is preferable because it can be done over HTTPS, which hides your credentials. That is not the case for SOCKS5. However, SOAX only supports TCP using HTTP CONNECT. For UDP, you will have to use SOCKS5 (see HTTP vs SOCKS5 vs HTTPS: Which proxy protocol should you use?)

Sessions

It's very important to use sessions in order to ensure your requests are using the same proxy. By default, you will get a different proxy for each request.

To use the same proxy, create a session by passing a sessionid and sessionlength, in seconds. Changing the session ID changes the proxy used. When session length expires, you may get a new proxy.

For advanced session parameters, see Understanding session parameters.

SOAX REST API

API Reference.

API calls require both an API key, tied to the account, and a Package key, tied to the purchased package.

Note that the APIs for mobile and residential packages differ a bit.

Get list of mobile carriers

This is for Mobile packages only.

Reference

Request format:

https://api.soax.com/api/get-country-operators?api_key=<api_key>&package_key=<package_key>&country_iso=<country_iso>[&region=<region_name>[&city=<city_name>]]

Here is an example of listing the mobile ISPs in Russia:

$ curl "https://api.soax.com/api/get-country-operators?api_key=$SOAX_API_KEY&package_key=$SOAX_PACKAGE_KEY&country_iso=ru"

["pjsc megafon","mts pjsc","tele2 russia","beeline","rostelecom","jsc ufanet","edinos","ekaterinburg-2000","tbank jsc","er-telecom","t-mob","mcs","dom.ru","sberbank-telecom","llc sp abaza telecom","s.u.e. dpr republic operator of networks","tattelecom","edinos ltd.","invest mobile","isp balzer-telecom","innovation solutions center ltd.","novokuznetsk telecom","mobile trend","ooo network of data-centers selectel","dagnet","jv a-mobile","llc alfa-mobile","zao aquafon-gsm","ooo vtc-mobile"]
Get list of residential ISPs

This is for Residential packages only. The official documentation refers to them as "WiFi ISPs".

Reference

Request format:

https://api.soax.com/api/get-country-isp?api_key=<api_key>&package_key=<package_key>&country_iso=<country_iso>[&region=<region_name>[&city=<city_name>]]
Get list of regions

Reference

Request format:

https://api.soax.com/api/get-country-regions?api_key=<api_key>&package_key=<package_key>&country_iso=<country_iso>&conn_type=<conn_type>[&provider=<provider>]

The conn_type parameter specifies the connection type. It must be wifi for residential proxies and mobile for mobile proxies.

Here is an example of listing regions in Iran:

$ curl  "https://api.soax.com/api/get-country-regions?api_key=$SOAX_API_KEY&package_key=$SOAX_PACKAGE_KEY&country_iso=ir&conn_type=mobile"

["tehran","razavi khorasan","fars","isfahan","khuzestan","east azerbaijan province","alborz province","mazandaran","west azerbaijan province","gilan province","qom province"]
Get list of cities

Reference

Request format:

https://api.soax.com/api/get-country-cities?api_key=<api_key>&package_key=<package_key>&country_iso=<country_iso>&conn_type=<conn_type>[&provider=<provider_name>[&region=<region_name>]]

The conn_type parameter specifies the connection type. It must be wifi for residential proxies and mobile for mobile proxies.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var SessionNotPersistent = SessionConfig{Duration: -1}

Indicates that the session should not persist. No session ID will be set and each request will get a different node.

Functions

This section is empty.

Types

type Client 

type Client struct {
	APIKey     string
	PackageKey string
	// ConnType is the connection type.
	ConnType ConnType
	// HTTPClient is the client to use for API calls. If nil, a default client will be used.
	HTTPClient *http.Client
	// BaseURL for testing. If empty, "https://api.soax.com" is used. This can be a plain URL, or one
	// with a path.
	BaseURL string
}

Client allows you to access the SOAX REST API.

func (*Client) GetCities 

func (c *Client) GetCities(ctx context.Context, countryCode, isp, regionID string) ([]string, error)

GetCities returns the available cities for the given country, ISP, and region. API reference: https://helpcenter.soax.com/en/articles/6228092-getting-a-list-of-cities

func (*Client) GetMobileISPs 

func (c *Client) GetMobileISPs(ctx context.Context, countryCode, regionID, cityID string) ([]string, error)

GetMobileISPs returns the available mobile carriers for the given location. This is for Mobile packages only. API reference: https://helpcenter.soax.com/en/articles/6228381-getting-a-list-of-mobile-carriers

func (*Client) GetRegions 

func (c *Client) GetRegions(ctx context.Context, countryCode, isp string) ([]string, error)

GetRegions returns the available regions for the given country and ISP. API reference: https://helpcenter.soax.com/en/articles/6227864-getting-a-list-of-regions

func (*Client) GetResidentialISPs 

func (c *Client) GetResidentialISPs(ctx context.Context, countryCode, regionID, cityID string) ([]string, error)

GetResidentialISPs returns the available ISPs for the given location. This is for Residential packages only. The official documentation refers to them as "WiFi ISPS". API reference: https://helpcenter.soax.com/en/articles/6228391-getting-a-list-of-wifi-isps

type ConnType 

type ConnType string

ConnType specifies the connection type for SOAX API calls. 

const (
	// ConnTypeResidential is for residential proxies, referred to as "wifi" by the API.
	ConnTypeResidential ConnType = "wifi"
	// ConnTypeMobile is for mobile proxies.
	ConnTypeMobile ConnType = "mobile"
)

type ProxyAuthConfig 

type ProxyAuthConfig struct {
	PackageID  int
	PackageKey string
}

ProxyAuthConfig represents the authentication credentials for the SOAX proxy.

type ProxyNodeConfig 

type ProxyNodeConfig struct {
	CountryCode string
	RegionID    string
	CityID      string
	ISPID       string
}

ProxyNodeConfig defines the geographic and network restrictions for the proxy node.

type ProxySession 

type ProxySession struct {
	// contains filtered or unexported fields
}

ProxySession represents a session with unique SessionID, created from a SessionConfig.

func (*ProxySession) NewSOCKS5Client 

func (c *ProxySession) NewSOCKS5Client() (*socks5.Client, error)

NewSOCKS5Client creates a socks5.Client that connects through the SOAX proxy.

func (*ProxySession) NewWebProxyStreamDialer 

func (c *ProxySession) NewWebProxyStreamDialer() (transport.StreamDialer, error)

NewStreamDialer creates a transport.StreamDialer that connects through the SOAX proxy. It uses HTTP CONNECT, so it only supports TCP.

type ProxySessionConfig 

type ProxySessionConfig struct {
	// Authentication credentials
	Auth ProxyAuthConfig

	// Node restrictions
	Node ProxyNodeConfig

	// Session management
	// Set to SessionNotPersistent to disable session persistence and get different nodes per request.
	Session SessionConfig

	// Endpoint address. If empty, defaults to proxy.soax.com:5000.
	// Useful for testing or reverse proxies.
	Endpoint string
}

ProxySessionConfig defines how to connect to the SOAX proxy.

func (*ProxySessionConfig) NewSession 

func (c *ProxySessionConfig) NewSession() *ProxySession

type SessionConfig 

type SessionConfig struct {
	// Unique ID for this session
	ID string
	// How long this session should last
	Duration time.Duration
	// Rotate the node if the session goes idle for longer than this.
	IdleTTL time.Duration
}

SessionConfig defines the session management parameters for the proxy.

Source Files

View all Source files

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.