response.go

package ipwhois

// Response is the result of a single-IP lookup.
//
// Always check Success first. On success, the typed fields below carry the
// API data. On failure, Message (and optionally ErrorType, HTTPStatus,
// RetryAfter) describe the error.
//
// The library never panics and never returns a Go error — every failure
// (API error, network error, bad input, missing dependency) comes back as
// a Response with Success=false and a Message.
type Response struct {
	// Success indicates whether the lookup completed successfully.
	// On any failure this is false and Message describes the cause.
	Success bool `json:"success"`

	// Message contains a human-readable error description on failure,
	// or is empty on success.
	Message string `json:"message,omitempty"`

	// ErrorType categorises the error so callers can branch on the cause:
	//   - ErrorTypeAPI              — error returned by the ipwhois.io API
	//                                 (HTTP 4xx/5xx, malformed JSON, or a
	//                                 2xx body with success=false such as
	//                                 "Invalid IP address" / "Reserved range")
	//   - ErrorTypeNetwork          — DNS / connection / timeout
	//   - ErrorTypeEnvironment      — missing dependency or runtime error
	//   - ErrorTypeInvalidArgument  — bad option passed to the library
	ErrorType string `json:"error_type,omitempty"`

	// HTTPStatus is set on HTTP 4xx / 5xx responses from the API.
	HTTPStatus int `json:"http_status,omitempty"`

	// RetryAfter is set on HTTP 429 responses from the free-plan endpoint
	// (ipwho.is) when the API sent a Retry-After header. Value is in
	// seconds. The paid endpoint (ipwhois.pro) does not send the header,
	// so this field is not populated on paid-plan rate-limit responses.
	RetryAfter int `json:"retry_after,omitempty"`

	// IP geolocation data — populated on success.

	IP            string  `json:"ip,omitempty"`
	Type          string  `json:"type,omitempty"`
	Continent     string  `json:"continent,omitempty"`
	ContinentCode string  `json:"continent_code,omitempty"`
	Country       string  `json:"country,omitempty"`
	CountryCode   string  `json:"country_code,omitempty"`
	Region        string  `json:"region,omitempty"`
	RegionCode    string  `json:"region_code,omitempty"`
	City          string  `json:"city,omitempty"`
	Latitude      float64 `json:"latitude,omitempty"`
	Longitude     float64 `json:"longitude,omitempty"`
	IsEU          bool    `json:"is_eu,omitempty"`
	Postal        string  `json:"postal,omitempty"`
	CallingCode   string  `json:"calling_code,omitempty"`
	Capital       string  `json:"capital,omitempty"`
	Borders       string  `json:"borders,omitempty"`

	Flag       *Flag       `json:"flag,omitempty"`
	Connection *Connection `json:"connection,omitempty"`
	Timezone   *Timezone   `json:"timezone,omitempty"`
	Currency   *Currency   `json:"currency,omitempty"`
	Security   *Security   `json:"security,omitempty"`
	Rate       *Rate       `json:"rate,omitempty"`

	// Raw is the unmodified response body. Useful as an escape hatch for
	// fields not yet typed by this struct, e.g. when the API adds a new
	// field that hasn't made it into the Go struct definition yet.
	Raw []byte `json:"-"`
}

// Flag describes the country flag block.
type Flag struct {
	Img          string `json:"img,omitempty"`
	Emoji        string `json:"emoji,omitempty"`
	EmojiUnicode string `json:"emoji_unicode,omitempty"`
}

// Connection describes the network connection block.
type Connection struct {
	ASN    int    `json:"asn,omitempty"`
	Org    string `json:"org,omitempty"`
	ISP    string `json:"isp,omitempty"`
	Domain string `json:"domain,omitempty"`
}

// Timezone describes the timezone block.
type Timezone struct {
	ID          string `json:"id,omitempty"`
	Abbr        string `json:"abbr,omitempty"`
	IsDST       bool   `json:"is_dst,omitempty"`
	Offset      int    `json:"offset,omitempty"`
	UTC         string `json:"utc,omitempty"`
	CurrentTime string `json:"current_time,omitempty"`
}

// Currency describes the currency block.
type Currency struct {
	Name         string  `json:"name,omitempty"`
	Code         string  `json:"code,omitempty"`
	Symbol       string  `json:"symbol,omitempty"`
	Plural       string  `json:"plural,omitempty"`
	ExchangeRate float64 `json:"exchange_rate,omitempty"`
}

// Security describes the threat-detection block (paid plan).
type Security struct {
	Anonymous bool `json:"anonymous,omitempty"`
	Proxy     bool `json:"proxy,omitempty"`
	VPN       bool `json:"vpn,omitempty"`
	Tor       bool `json:"tor,omitempty"`
	Hosting   bool `json:"hosting,omitempty"`
}

// Rate describes the rate-limit block.
type Rate struct {
	Limit     int `json:"limit,omitempty"`
	Remaining int `json:"remaining,omitempty"`
}

// BulkResponse is the result of a multi-IP lookup.
//
// On whole-batch failure (network error, bad API key, rate limit, …)
// Success is false and Message describes the failure. Otherwise Results
// holds one entry per requested IP, each with its own Success flag —
// per-IP failures (e.g. "Invalid IP address") are returned inline and
// the rest of the batch remains usable.
type BulkResponse struct {
	// Success indicates whether the bulk request as a whole succeeded.
	// When true, iterate Results. When false, check Message.
	Success bool

	// Message contains a human-readable error description on whole-batch
	// failure, or is empty on success.
	Message string

	// ErrorType categorises the error. See Response.ErrorType for the
	// full list of values.
	ErrorType string

	// HTTPStatus is set on HTTP 4xx / 5xx whole-batch responses.
	HTTPStatus int

	// RetryAfter is set on HTTP 429 responses from the free-plan endpoint
	// (ipwho.is) when the API sent a Retry-After header. Value is in
	// seconds. The paid endpoint (ipwhois.pro) does not send the header,
	// so this field is not populated on paid-plan rate-limit responses.
	RetryAfter int

	// Results contains per-IP results. Populated only when Success is true.
	// Each entry has its own Success flag — check it before reading the
	// geolocation fields.
	Results []*Response

	// Raw is the unmodified response body.
	Raw []byte
}