reverseip

README

Overview

The client library for Reverse IP/DNS 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/reverse-ip-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 := reverseip.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 := reverseip.NewClient(apiKey, reverseip.ClientParams{
    HTTPClient: &http.Client{
        Transport: transport,
        Timeout:   20 * time.Second,
    },
})

Make basic requests

Reverse IP/DNS API lets you get a list of all domains associated with an IP address.

// Make request to get a list of all domains by IP address as a model instance.
reverseIPResp, _, err := client.Get(ctx, []byte{8,8,8,8})
if err != nil {
    log.Fatal(err)
}

for _, obj := range reverseIPResp.Result {
    log.Println(obj.Name, obj.FirstSeen, obj.LastVisit)
}

// Make request to get raw data in XML.
resp, err := client.GetRaw(context.Background(), net.IP{1, 1, 1, 1},
    reverseip.OptionOutputFormat("XML"))
if err != nil {
    log.Fatal(err)
}

log.Println(string(resp.Body))

Advanced usage

Pagination

// Each response is limited to 300 records.
const limit = 300
from := "1"

for {
    reverseIPResp, _, err := client.Get(context.Background(), []byte{8, 8, 8, 8},
    //  This option results in the next page is retrieved.
    reverseip.OptionFrom(from))
    if err != nil {
        log.Fatal(err)
    }

    for _, obj := range reverseIPResp.Result {
        log.Println(obj.Name)
    }

    // Break the loop when the last page is reached.
    if reverseIPResp.Size < limit {
        break
    }
    from = reverseIPResp.Result[reverseIPResp.Size-1].Name
}

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 OptionFrom(value string) Option
  • func OptionOutputFormat(outputFormat string) Option
• type Response
• type Result
• type ReverseIP
• type ReverseIPResponse

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 {

	// ReverseIP is an interface for Reverse IP/DNS API
	ReverseIP
	// contains filtered or unexported fields
}

Client is the client for Reverse IP/DNS 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

	// ReverseIPBaseURL is the endpoint for 'Reverse IP/DNS API' service
	ReverseIPBaseURL *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 the 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 OptionFrom

func OptionFrom(value string) Option

OptionFrom sets the domain name which is used as an offset for the results returned.

func OptionOutputFormat

func OptionOutputFormat(outputFormat string) Option

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

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 {
	// Name is the domain name.
	Name string `json:"name"`

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

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

Result is a part of the Reverse IP/DNS API response.

type ReverseIP

type ReverseIP interface {
	// Get returns parsed Reverse IP/DNS API response.
	Get(ctx context.Context, ip net.IP, opts ...Option) (*ReverseIPResponse, *Response, error)

	// GetRaw returns raw Reverse IP/DNS API response as the Response struct with Body saved as a byte slice.
	GetRaw(ctx context.Context, ip net.IP, opts ...Option) (*Response, error)
}

ReverseIP is an interface for Reverse IP/DNS API.

type ReverseIPResponse

type ReverseIPResponse struct {
	// Result is a segment that contains info about the resulting data.
	Result []Result `json:"result"`

	// CurrentPage is the selected page.
	CurrentPage string `json:"current_page"`

	// Size is the number of records in the Result segment.
	Size int `json:"size"`
}

ReverseIPResponse is a response of Reverse IP/DNS API.