subdomainslookup

README

Overview

The client library for Subdomains Lookup API in Go language.

The minimum go version is 1.17.

Installation

The library is distributed as a Go module

go get github.com/whois-api-llc/subdomains-lookup-go

Examples

Full API documentation available here

You can find all examples in example directory.

Create a new client

To start making requests you need the API Key. You can find it on your profile page on whoisxmlapi.com. Using the API Key you can create Client.

Most users will be fine with NewBasicClient function.

client := subdomainslookup.NewBasicClient(apiKey)

If you want to set custom http.Client to use proxy then you can use NewClient function.

transport := &http.Transport{Proxy: http.ProxyURL(proxyUrl)}

client := subdomainslookup.NewClient(apiKey, subdomainslookup.ClientParams{
    HTTPClient: &http.Client{
        Transport: transport,
        Timeout:   20 * time.Second,
    },
})

Make basic requests

Subdomains Lookup API lets you get a list of all subdomains related to a given domain name.

// Make request to get all subdomains for the domain name.
subdomainsLookupResp, resp, err := client.Get(ctx, "whoisxmlapi.com")
if err != nil {
    log.Fatal(err)
}

for _, obj := range subdomainsLookupResp.Result.Records {
    log.Printf("Domain: %s, FirstSeen: %s, LastSeen: %s\n", 
		obj.Domain, 
		time.Unix(obj.FirstSeen, 0).Format(time.RFC3339), 
		time.Unix(obj.LastSeen, 0).Format(time.RFC3339),
    )
}

// Make request to get raw data from Subdomains Lookup API.
resp, err := client.GetRaw(context.Background(), "whoisxmlapi.com")
if err != nil {
    log.Fatal(err)
}

log.Println(string(resp.Body))

Documentation

Index

• type ArgError
  • func (a *ArgError) Error() string
• type Client
  • func NewBasicClient(apiKey string) *Client
  • func NewClient(apiKey string, params ClientParams) *Client
  • func (c *Client) Do(ctx context.Context, req *http.Request, v io.Writer) (response *http.Response, err error)
  • func (c *Client) NewRequest(method string, u *url.URL, body io.Reader) (*http.Request, error)
• type ClientParams
• type ErrorMessage
  • func (e *ErrorMessage) Error() string
• type ErrorResponse
  • func (e *ErrorResponse) Error() string
• type Option
  • func OptionOutputFormat(outputFormat string) Option
• type Record
• type Response
• type Result
• type SubdomainsLookup
• type SubdomainsLookupResponse

Types

type ArgError

type ArgError struct {
	Name    string
	Message string
}

ArgError is the argument error.

func (*ArgError) Error

func (a *ArgError) Error() string

Error returns error message as a string.

type Client

type Client struct {

	// SubdomainsLookup is an interface for Subdomains Lookup API
	SubdomainsLookup
	// contains filtered or unexported fields
}

Client is the client for Subdomains Lookup API services.

func NewBasicClient

func NewBasicClient(apiKey string) *Client

NewBasicClient creates Client with recommended parameters.

func NewClient

func NewClient(apiKey string, params ClientParams) *Client

NewClient creates Client with specified parameters.

func (*Client) Do

func (c *Client) Do(ctx context.Context, req *http.Request, v io.Writer) (response *http.Response, err error)

Do sends the API request and returns the API response.

func (*Client) NewRequest

func (c *Client) NewRequest(method string, u *url.URL, body io.Reader) (*http.Request, error)

NewRequest creates a basic API request.

type ClientParams

type ClientParams struct {
	// HTTPClient is the client used to access API endpoint
	// If it's nil then value API client uses http.DefaultClient
	HTTPClient *http.Client

	// SubdomainsLookupBaseURL is the endpoint for 'Subdomains Lookup API' service
	SubdomainsLookupBaseURL *url.URL
}

ClientParams is used to create Client. None of parameters are mandatory and leaving this struct empty works just fine for most cases.

type ErrorMessage

type ErrorMessage struct {
	Code    int    `json:"code"`
	Message string `json:"messages"`
}

ErrorMessage is an error message.

func (*ErrorMessage) Error

func (e *ErrorMessage) Error() string

Error returns error message as a string.

type ErrorResponse

type ErrorResponse struct {
	Response *http.Response
	Message  string
}

ErrorResponse is returned when the response status code is not 2xx.

func (*ErrorResponse) Error

func (e *ErrorResponse) Error() string

Error returns error message as a string.

type Option

type Option func(v url.Values)

Option adds parameters to the query.

func OptionOutputFormat

func OptionOutputFormat(outputFormat string) Option

OptionOutputFormat sets Response output format JSON | XML. Default: JSON.

type Record

type Record struct {
	// Domain is the domain name.
	Domain string `json:"domain"`

	// FirstSeen is the timestamp of the first time that the record was seen.
	FirstSeen int64 `json:"firstSeen"`

	// LastSeen is the timestamp of the last update for this record.
	LastSeen int64 `json:"lastSeen"`
}

Record contains info about subdomain: a domain name and timestamps.

type Response

type Response struct {
	*http.Response

	// Body is the byte slice representation of http.Response Body
	Body []byte
}

Response is the http.Response wrapper with Body saved as a byte slice.

type Result

type Result struct {
	// Count is the number of records in result segment.
	Count int `json:"count"`

	// Records contains info about the resulting data: a domain name and timestamps.
	Records []Record `json:"records"`
}

Result is the resulting object.

type SubdomainsLookup

type SubdomainsLookup interface {
	// Get returns parsed Subdomains Lookup API response
	Get(ctx context.Context, domainName string, opts ...Option) (*SubdomainsLookupResponse, *Response, error)

	// GetRaw returns raw Subdomains Lookup API response as Response struct with Body saved as a byte slice
	GetRaw(ctx context.Context, domainName string, opts ...Option) (*Response, error)
}

SubdomainsLookup is an interface for Subdomains Lookup API.

type SubdomainsLookupResponse

type SubdomainsLookupResponse struct {
	// Search is the target domain name.
	Search string `json:"search"`

	// Result is the resulting object.
	Result Result `json:"result"`
}

SubdomainsLookupResponse is a response of Subdomains Lookup API.