registrantalert

README

Overview

The client library for Registrant Alert 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/registrant-alert-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 := registrantalert.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 := registrantalert.NewClient(apiKey, registrantalert.ClientParams{
    HTTPClient: &http.Client{
        Transport: transport,
        Timeout:   20 * time.Second,
    },
})

Make basic requests

Registrant Alert API lets you monitor specific domain registrants to be alerted whenever their information is linked to a newly-registered or just-expired domain name.

Basic search requires less configuration and produces broader results.

// Make request to get a list of all domains matching the criteria.
registrantAlertResp, _, err := client.BasicPurchase(ctx,
    &registrantalert.BasicSearchTerms{[]string{"Airbnb", "US"}, []string{"Europe", "EU"}})

for _, obj := range registrantAlertResp.DomainsList {
    log.Println(obj.DomainName)
}


// Make request to get only domains count.
domainsCount, _, err := client.BasicPreview(ctx,
    &registrantalert.BasicSearchTerms{[]string{"Google"}})

log.Println(domainsCount)

// Make request to get raw data in XML.
resp, err := client.BasicRawData(ctx,
    &registrantalert.SearchTerms{"google", "blog"},
    &registrantalert.SearchTerms{"analytics"},
    registrantalert.OptionResponseFormat("XML"))

log.Println(string(resp.Body))

Advanced usage

Advanced search allows searching through specific WHOIS fields.

registrantAlertResp, resp, err := client.AdvancedPurchase(ctx,
    []registrantalert.AdvancedSearchTerm{{"RegistrantContact.Organization", "Airbnb, Inc.", true}},
    registrantalert.OptionSinceDate(time.Date(2022, 11, 01, 0, 0, 0, 0, time.UTC)))

Documentation

Index

• type Action
• type AdvancedSearchTerm
• type ArgError
  • func (a *ArgError) Error() string
• type BasicSearchTerms
• 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 DomainItem
• type ErrorMessage
  • func (e *ErrorMessage) Error() string
• type ErrorResponse
  • func (e *ErrorResponse) Error() string
• type Messages
  • func (m *Messages) UnmarshalJSON(b []byte) error
• type Option
  • func OptionCreatedDateFrom(date time.Time) Option
  • func OptionCreatedDateTo(date time.Time) Option
  • func OptionExpiredDateFrom(date time.Time) Option
  • func OptionExpiredDateTo(date time.Time) Option
  • func OptionPunycode(punycode bool) Option
  • func OptionResponseFormat(outputFormat string) Option
  • func OptionSinceDate(date time.Time) Option
  • func OptionUpdatedDateFrom(date time.Time) Option
  • func OptionUpdatedDateTo(date time.Time) Option
• type RegistrantAlert
• type RegistrantAlertResponse
• type Response
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(b []byte) error

Types

type Action

type Action string

Action is a wrapper on string.

const (
	Added      Action = "added"
	Updated    Action = "updated"
	Dropped    Action = "dropped"
	Discovered Action = "discovered"
)

List of possible actions.

type AdvancedSearchTerm

type AdvancedSearchTerm struct {
	// Field is the WHOIS field to search in.
	Field string `json:"field"`

	// Term is the search string. Case insensitive.
	Term string `json:"term"`

	// ExactMatch defines whether the field should exactly match the search term.
	// If false, the field is allowed to contain a search term as a substring.
	ExactMatch bool `json:"exactMatch,omitempty"`
}

AdvancedSearchTerm is a part of the Registrant Alert API request.

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 BasicSearchTerms

type BasicSearchTerms struct {
	// Include is an array of search strings.
	// All of them should be present in the domain's registrant details.
	Include []string `json:"include,omitempty"`

	// Exclude is an array of search strings.
	// All of them should NOT be present in the domain's registrant details.
	Exclude []string `json:"exclude,omitempty"`
}

BasicSearchTerms is a part of the Registrant Alert API request.

type Client

type Client struct {

	// RegistrantAlert is an interface for Registrant Alert API
	RegistrantAlert
	// contains filtered or unexported fields
}

Client is the client for Registrant Alert 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

	// RegistrantAlertBaseURL is the endpoint for 'Registrant Alert API' service
	RegistrantAlertBaseURL *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 DomainItem

type DomainItem struct {
	// DomainName is the full domain name.
	DomainName string `json:"domainName"`

	// Action is the related action. Possible actions: added | updated | dropped | discovered.
	Action Action `json:"action"`

	// Date is the event date.
	Date Time `json:"date"`
}

DomainItem is a part of the Registrant Alert API response.

type ErrorMessage

type ErrorMessage struct {
	Code    int      `json:"code"`
	Message Messages `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 Messages

type Messages []string

Messages is a wrapper on []string.

func (*Messages) UnmarshalJSON

func (m *Messages) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes the error messages returned by Registrant Alert API.

type Option

type Option func(v *registrantAlertRequest)

Option adds parameters to the query.

func OptionCreatedDateFrom

func OptionCreatedDateFrom(date time.Time) Option

OptionCreatedDateFrom searches through domains created after the given date.

func OptionCreatedDateTo

func OptionCreatedDateTo(date time.Time) Option

OptionCreatedDateTo searches through domains created before the given date.

func OptionExpiredDateFrom

func OptionExpiredDateFrom(date time.Time) Option

OptionExpiredDateFrom searches through domains expired after the given date.

func OptionExpiredDateTo

func OptionExpiredDateTo(date time.Time) Option

OptionExpiredDateTo searches through domains expired before the given date.

func OptionPunycode

func OptionPunycode(punycode bool) Option

OptionPunycode sets the punycode option. If true, domain names in the response will be encoded to Punycode. Default: true.

func OptionResponseFormat

func OptionResponseFormat(outputFormat string) Option

OptionResponseFormat sets Response output format json | xml. Default: json.

func OptionSinceDate

func OptionSinceDate(date time.Time) Option

OptionSinceDate results in search through activities discovered since the given date.

func OptionUpdatedDateFrom

func OptionUpdatedDateFrom(date time.Time) Option

OptionUpdatedDateFrom searches through domains updated after the given date.

func OptionUpdatedDateTo

func OptionUpdatedDateTo(date time.Time) Option

OptionUpdatedDateTo searches through domains updated before the given date.

type RegistrantAlert

type RegistrantAlert interface {
	// BasicPreview returns only the number of domains for the basic search. No credits deducted.
	BasicPreview(ctx context.Context, basicSearchTerms *BasicSearchTerms, option ...Option) (int, *Response, error)

	// BasicPurchase returns parsed Registrant Alert API response for the basic search.
	BasicPurchase(ctx context.Context, basicSearchTerms *BasicSearchTerms, option ...Option) (*RegistrantAlertResponse, *Response, error)

	// BasicRawData returns raw Registrant Alert API response for the basic search.
	BasicRawData(ctx context.Context, basicSearchTerms *BasicSearchTerms, option ...Option) (*Response, error)

	// AdvancedPreview returns only the number of domains for the advanced search. No credits deducted.
	AdvancedPreview(ctx context.Context, advancedSearchTerms []AdvancedSearchTerm, option ...Option) (int, *Response, error)

	// AdvancedPurchase returns parsed Registrant Alert API response for the advanced search.
	AdvancedPurchase(ctx context.Context, advancedSearchTerms []AdvancedSearchTerm, option ...Option) (*RegistrantAlertResponse, *Response, error)

	// AdvancedRawData returns raw Registrant Alert API response for the advanced search.
	AdvancedRawData(ctx context.Context, advancedSearchTerms []AdvancedSearchTerm, option ...Option) (*Response, error)
}

RegistrantAlert is an interface for Registrant Alert API.

type RegistrantAlertResponse

type RegistrantAlertResponse struct {
	// DomainsList is the list of domains matching the criteria.
	DomainsList []DomainItem `json:"domainsList"`

	// DomainsCount is the number of domains matching the criteria.
	DomainsCount int `json:"domainsCount"`
}

RegistrantAlertResponse is a response of Registrant Alert API.

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 Time

type Time time.Time

Time is a helper wrapper on time.Time

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON encodes time as Registrant Alert API does.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes time as Registrant Alert API does.