websitecategorization

README

Overview

The client library for Website Categorization 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/website-categorization-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 := websitecategorization.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 := websitecategorization.NewClient(apiKey, websitecategorization.ClientParams{
    HTTPClient: &http.Client{
        Transport: transport,
        Timeout:   20 * time.Second,
    },
})

Make basic requests

Website Categorization API lets you get top Internet Advertising Bureau (IAB) categories for websites.

// Make request to get a list of categories by a domain name as a model instance.
wCategorizationResp, _, err := client.Get(ctx, "whoisxmlapi.com")
if err != nil {
    log.Fatal(err)
}

for _, obj := range wCategorizationResp.Categories {
	log.Printf("ID: %d, Name: %s, Confidence: %f ", obj.ID, obj.Name, obj.Tier1.Confidence)
}

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

log.Println(string(resp.Body))

Documentation

Index

• type AS
• type ArgError
  • func (a *ArgError) Error() string
• type Category
• type CategoryItem
• 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 OptionMinConfidence(value float64) Option
  • func OptionOrder(order string) Option
  • func OptionOutputFormat(outputFormat string) Option
• type Response
• type WCategorizationResponse
• type WCategorizationService

Types

type AS

type AS struct {
	// ASN Autonomous System Number.
	ASN int `json:"asn"`

	// Domain Autonomous System Website's URL.
	Domain string `json:"domain"`

	// Name Autonomous System Name.
	Name string `json:"name"`

	// Route Autonomous System Route.
	Route string `json:"route"`

	// Type Autonomous System Type.
	Type string `json:"type"`
}

AS is a part of the Website Categorization API response.

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 Category

type Category struct {
	// Confidence The probability of how the category may be relevant for the website.
	Confidence float64 `json:"confidence"`

	// ID The unique category identifier.
	ID int `json:"id"`

	// Name The readable name of the category.
	Name string `json:"name"`
}

Category is a part of the Website Categorization API v3 response.

type CategoryItem

type CategoryItem struct {
	// ID is the unique category identifier.
	ID int `json:"id"`

	// Name is the readable name of the category.
	Name string `json:"name"`
}

CategoryItem is part of the category directory.

type Client

type Client struct {

	// WCategorization is an interface for Website Categorization API
	WCategorizationService
	// contains filtered or unexported fields
}

Client is the client for Website Categorization 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

	// WCategorizationBaseURL is the endpoint for 'Website Categorization API' service
	WCategorizationBaseURL *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 OptionMinConfidence

func OptionMinConfidence(value float64) Option

OptionMinConfidence sets The minimum confidence for the predictions. The higher this value the fewer false-positive results will be returned. Acceptable values: 0.00 - 1.00. Default: 0.55.

func OptionOrder

func OptionOrder(order string) Option

OptionOrder sets the categories output order (for GetAllCategories functions only). ABC - output categories ordered alphabetically by the name field. ID - output categories ordered by the id field. Acceptable values: ABC | ID Default: ID.

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 WCategorizationResponse

type WCategorizationResponse struct {
	// AS Autonomous System.
	AS *AS `json:"as,omitempty"`

	// DomainName is a domain/website name.
	DomainName string `json:"domainName"`

	// Categories is the list of website's categories.
	Categories []Category `json:"categories"`

	// CreatedDate is date of initial creation of the WHOIS record for the domain in ISO8601 format. Omitted if the record is not found.
	CreatedDate *string `json:"createdDate,omitempty"`

	// WebsiteResponded Determines if the website was active during the crawling.
	WebsiteResponded bool `json:"websiteResponded"`
}

WCategorizationResponse is a response of Website Categorization API.

type WCategorizationService

type WCategorizationService interface {
	// Get returns parsed Website Categorization API response.
	Get(ctx context.Context, domainName string, opts ...Option) (*WCategorizationResponse, *Response, error)

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

	// GetAllCategories returns all possible categories.
	GetAllCategories(ctx context.Context, opts ...Option) (categories []CategoryItem, response *Response, err error)

	// GetAllCategoriesRaw returns all possible categories as a raw API response.
	GetAllCategoriesRaw(ctx context.Context, opts ...Option) (response *Response, err error)
}

WCategorizationService is an interface for Website Categorization API.