ipinfo

package
v2.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2023 License: Apache-2.0 Imports: 16 Imported by: 27

Documentation

Overview

Package ipinfo provides a client for using the IPinfo API.

Usage:

import "github.com/ipinfo/go/v2/ipinfo"

The default IPinfo client is predefined and can be used without initialization. For example:

info, err := ipinfo.GetIPInfo(net.ParseIP("8.8.8.8"))

Authorization

To perform authorized API calls with more data and higher limits, pass in a non-empty token to NewClient. For example:

client := ipinfo.NewClient(nil, nil, "MY_TOKEN")
info, err := client.GetIPInfo(net.ParseIP("8.8.8.8"))

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetContinentCode added in v2.9.1

func GetContinentCode(country string) string

GetContinentCode gets the continent code of a country from its code, e.g. "PK" -> "AS".

func GetContinentName added in v2.9.1

func GetContinentName(country string) string

GetContinentName gets the name of continent from country code, e.g. "PK" -> "Asia".

func GetCountryCurrencyCode added in v2.9.0

func GetCountryCurrencyCode(country string) string

GetCountryCurrencyCode gets the currency code of a country from its code, e.g. "PK" -> "PKR".

func GetCountryCurrencySymbol added in v2.9.0

func GetCountryCurrencySymbol(country string) string

GetCountryCurrencySymbol gets the symbol of currency from country code, e.g. "PK" -> "₨".

func GetCountryFlagEmoji added in v2.9.0

func GetCountryFlagEmoji(country string) string

GetCountryFlagEmoji gets the emoji flag of a country from its code, e.g. "PK" -> "🇵🇰".

func GetCountryFlagURL added in v2.9.3

func GetCountryFlagURL(country string) string

GetCountryFlagURL gets the URL of the country flag, e.g. "PK" -> "https://cdn.ipinfo.io/static/images/countries-flags/PK.svg".

func GetCountryFlagUnicode added in v2.9.0

func GetCountryFlagUnicode(country string) string

GetCountryFlagUnicode gets the unicode of an emoji from country code, e.g. "PK" -> "U+1F1F5 U+1F1F0".

func GetCountryName added in v2.2.2

func GetCountryName(country string) string

GetCountryName gets the full name of a country from its code, e.g. "PK" -> "Pakistan".

func GetIPAddr

func GetIPAddr() (string, error)

GetIPAddr returns the IP address that IPinfo sees when you make a request.

func GetIPAnycast added in v2.2.1

func GetIPAnycast(ip net.IP) (bool, error)

GetIPAnycast returns whether an IP is an anycast IP.

func GetIPBogon added in v2.3.2

func GetIPBogon(ip net.IP) (bool, error)

GetIPBogon returns whether an IP is a bogon IP.

func GetIPCity

func GetIPCity(ip net.IP) (string, error)

GetIPCity returns the city for the specified IP.

func GetIPCountry

func GetIPCountry(ip net.IP) (string, error)

GetIPCountry returns the country for the specified IP.

func GetIPCountryName

func GetIPCountryName(ip net.IP) (string, error)

GetIPCountryName returns the full country name for the specified IP.

func GetIPHostname

func GetIPHostname(ip net.IP) (string, error)

GetIPHostname returns the hostname of the domain on the specified IP.

func GetIPLocation

func GetIPLocation(ip net.IP) (string, error)

GetIPLocation returns the location for the specified IP.

func GetIPOrg

func GetIPOrg(ip net.IP) (string, error)

GetIPOrg returns the organization for the specified IP.

func GetIPPostal

func GetIPPostal(ip net.IP) (string, error)

GetIPPostal returns the postal for the specified IP.

func GetIPRegion

func GetIPRegion(ip net.IP) (string, error)

GetIPRegion returns the region for the specified IP.

func GetIPTimezone

func GetIPTimezone(ip net.IP) (string, error)

GetIPTimezone returns the timezone for the specified IP.

func IsEU added in v2.8.0

func IsEU(country string) bool

IsEU takes the country code and returns `true` if the country is a member of the EU, e.g. "SE" -> true

func SetCache

func SetCache(cache *Cache)

SetCache assigns a cache to the package-level client.

func SetToken

func SetToken(token string)

SetToken assigns a token to the package-level client.

Types

type ASNDetails

type ASNDetails struct {
	ASN         string             `json:"asn"`
	Name        string             `json:"name"`
	Country     string             `json:"country"`
	CountryName string             `json:"-"`
	Allocated   string             `json:"allocated"`
	Registry    string             `json:"registry"`
	Domain      string             `json:"domain"`
	NumIPs      uint64             `json:"num_ips"`
	Type        string             `json:"type"`
	Prefixes    []ASNDetailsPrefix `json:"prefixes"`
	Prefixes6   []ASNDetailsPrefix `json:"prefixes6"`
	Peers       []string           `json:"peers"`
	Upstreams   []string           `json:"upstreams"`
	Downstreams []string           `json:"downstreams"`
}

ASNDetails represents details for an ASN.

func GetASNDetails

func GetASNDetails(asn string) (*ASNDetails, error)

GetASNDetails returns the details for the specified ASN.

type ASNDetailsPrefix

type ASNDetailsPrefix struct {
	Netblock string `json:"netblock"`
	ID       string `json:"id"`
	Name     string `json:"name"`
	Country  string `json:"country"`
	Size     string `json:"size"`
	Status   string `json:"status"`
	Domain   string `json:"domain"`
}

ASNDetailsPrefix represents data for prefixes managed by an ASN.

type Batch added in v2.2.0

type Batch map[string]interface{}

Batch is a mapped result of any valid API endpoint (e.g. `<ip>`, `<ip>/<field>`, `<asn>`, etc) to its corresponding data.

The corresponding value will be either `*Core`, `*ASNDetails` or a generic map for unknown value results.

func GetBatch added in v2.2.0

func GetBatch(
	urls []string,
	opts BatchReqOpts,
) (Batch, error)

GetBatch does a batch request for all `urls` at once.

type BatchASNDetails added in v2.2.0

type BatchASNDetails map[string]*ASNDetails

BatchASNDetails is a mapped result of ASNs to their corresponding `ASNDetails` data.

func GetASNDetailsBatch added in v2.2.0

func GetASNDetailsBatch(
	asns []string,
	opts BatchReqOpts,
) (BatchASNDetails, error)

GetASNDetailsBatch does a batch request for all `asns` at once.

type BatchCore added in v2.2.0

type BatchCore map[string]*Core

BatchCore is a mapped result of IPs to their corresponding `Core` data.

func GetIPInfoBatch added in v2.2.0

func GetIPInfoBatch(
	ips []net.IP,
	opts BatchReqOpts,
) (BatchCore, error)

GetIPInfoBatch does a batch request for all `ips` at once.

func GetIPStrInfoBatch added in v2.2.0

func GetIPStrInfoBatch(
	ips []string,
	opts BatchReqOpts,
) (BatchCore, error)

GetIPStrInfoBatch does a batch request for all `ips` at once.

type BatchReqOpts added in v2.2.0

type BatchReqOpts struct {
	// BatchSize is the internal batch size used per API request; the IPinfo
	// API has a maximum batch size, but the batch request functions available
	// in this library do not. Therefore the library chunks the input slices
	// internally into chunks of size `BatchSize`, clipping to the maximum
	// allowed by the IPinfo API.
	//
	// 0 means to use the default batch size which is the max allowed by the
	// IPinfo API.
	BatchSize uint32

	// TimeoutPerBatch is the timeout in seconds that each batch of size
	// `BatchSize` will have for its own request.
	//
	// 0 means to use a default of 5 seconds; any negative number will turn it
	// off; turning it off does _not_ disable the effects of `TimeoutTotal`.
	TimeoutPerBatch int64

	// TimeoutTotal is the total timeout in seconds for all batch requests in a
	// batch request function to complete.
	//
	// 0 means no total timeout; `TimeoutPerBatch` will still apply.
	TimeoutTotal uint64

	// ConcurrentBatchRequestsLimit is the maximum number of concurrent batch
	// requests that will be mid-flight for inputs that exceed the batch limit.
	//
	// 0 means to use a default of 8; any negative number implies unlimited concurrency.
	ConcurrentBatchRequestsLimit int

	// Filter, if turned on, will filter out a URL whose value was deemed empty
	// on the server.
	Filter bool
}

BatchReqOpts are options input into batch request functions.

type Cache

type Cache struct {
	cache.Interface
}

Cache represents the internal cache used by the IPinfo client.

func NewCache

func NewCache(engine cache.Interface) *Cache

NewCache creates a new cache given a specific engine.

type Client

type Client struct {

	// Base URL for API requests. BaseURL should always be specified with a
	// trailing slash.
	BaseURL *url.URL

	// User agent used when communicating with the IPinfo API.
	UserAgent string

	// Cache interface implementation to prevent API quota overuse for
	// identical requests.
	Cache *Cache

	// The API token used for authorization for more data and higher limits.
	Token string
	// contains filtered or unexported fields
}

A Client is the main handler to communicate with the IPinfo API.

var DefaultClient *Client

DefaultClient is the package-level client available to the user.

func NewClient

func NewClient(
	httpClient *http.Client,
	cache *Cache,
	token string,
) *Client

NewClient returns a new IPinfo API client.

If `httpClient` is nil, `http.DefaultClient` will be used.

If `cache` is nil, no cache is automatically assigned. You may set one later at any time with `client.SetCache`.

If `token` is empty, the API will be queried without any token. You may set one later at any time with `client.SetToken`.

func (*Client) GetASNDetails

func (c *Client) GetASNDetails(asn string) (*ASNDetails, error)

GetASNDetails returns the details for the specified ASN.

func (*Client) GetASNDetailsBatch added in v2.2.0

func (c *Client) GetASNDetailsBatch(
	asns []string,
	opts BatchReqOpts,
) (BatchASNDetails, error)

GetASNDetailsBatch does a batch request for all `asns` at once.

func (*Client) GetBatch added in v2.2.0

func (c *Client) GetBatch(
	urls []string,
	opts BatchReqOpts,
) (Batch, error)

GetBatch does a batch request for all `urls` at once.

func (*Client) GetIPASN

func (c *Client) GetIPASN(ip net.IP) (*CoreASN, error)

GetIPASN returns the ASN details for the specified IP.

func (*Client) GetIPAbuse

func (c *Client) GetIPAbuse(ip net.IP) (*CoreAbuse, error)

GetIPAbuse returns the abuse details for the specified IP.

func (*Client) GetIPAddr

func (c *Client) GetIPAddr() (string, error)

GetIPAddr returns the IP address that IPinfo sees when you make a request.

func (*Client) GetIPAnycast added in v2.2.1

func (c *Client) GetIPAnycast(ip net.IP) (bool, error)

GetIPAnycast returns whether an IP is an anycast IP.

func (*Client) GetIPBogon added in v2.3.2

func (c *Client) GetIPBogon(ip net.IP) (bool, error)

GetIPBogon returns whether an IP is a bogon IP.

func (*Client) GetIPCarrier

func (c *Client) GetIPCarrier(ip net.IP) (*CoreCarrier, error)

GetIPCarrier returns the carrier details for the specified IP.

func (*Client) GetIPCity

func (c *Client) GetIPCity(ip net.IP) (string, error)

GetIPCity returns the city for the specified IP.

func (*Client) GetIPCompany

func (c *Client) GetIPCompany(ip net.IP) (*CoreCompany, error)

GetIPCompany returns the company details for the specified IP.

func (*Client) GetIPCountry

func (c *Client) GetIPCountry(ip net.IP) (string, error)

GetIPCountry returns the country for the specified IP.

func (*Client) GetIPCountryName

func (c *Client) GetIPCountryName(ip net.IP) (string, error)

GetIPCountryName returns the full country name for the specified IP.

func (*Client) GetIPDomains

func (c *Client) GetIPDomains(ip net.IP) (*CoreDomains, error)

GetIPDomains returns the domains details for the specified IP.

func (*Client) GetIPHostname

func (c *Client) GetIPHostname(ip net.IP) (string, error)

GetIPHostname returns the hostname of the domain on the specified IP.

func (*Client) GetIPInfo

func (c *Client) GetIPInfo(ip net.IP) (*Core, error)

GetIPInfo returns the details for the specified IP.

func (*Client) GetIPInfoBatch added in v2.2.0

func (c *Client) GetIPInfoBatch(
	ips []net.IP,
	opts BatchReqOpts,
) (BatchCore, error)

GetIPInfoBatch does a batch request for all `ips` at once.

func (*Client) GetIPInfoV6 added in v2.10.0

func (c *Client) GetIPInfoV6(ip net.IP) (*Core, error)

GetIPInfoV6 returns the details for the specified IPv6 IP.

func (*Client) GetIPLocation

func (c *Client) GetIPLocation(ip net.IP) (string, error)

GetIPLocation returns the location for the specified IP.

func (*Client) GetIPMap added in v2.4.0

func (c *Client) GetIPMap(ips []net.IP) (*IPMap, error)

GetIPMap returns an IPMap result for a group of IPs.

`len(ips)` must not exceed 500,000.

func (*Client) GetIPOrg

func (c *Client) GetIPOrg(ip net.IP) (string, error)

GetIPOrg returns the organization for the specified IP.

func (*Client) GetIPPostal

func (c *Client) GetIPPostal(ip net.IP) (string, error)

GetIPPostal returns the postal for the specified IP.

func (*Client) GetIPPrivacy

func (c *Client) GetIPPrivacy(ip net.IP) (*CorePrivacy, error)

GetIPPrivacy returns the privacy details for the specified IP.

func (*Client) GetIPRegion

func (c *Client) GetIPRegion(ip net.IP) (string, error)

GetIPRegion returns the region for the specified IP.

func (*Client) GetIPStrInfoBatch added in v2.2.0

func (c *Client) GetIPStrInfoBatch(
	ips []string,
	opts BatchReqOpts,
) (BatchCore, error)

GetIPStrInfoBatch does a batch request for all `ips` at once.

func (*Client) GetIPSummary added in v2.3.0

func (c *Client) GetIPSummary(ips []net.IP) (*IPSummary, error)

GetIPSummary returns summarized results for a group of IPs.

func (*Client) GetIPTimezone

func (c *Client) GetIPTimezone(ip net.IP) (string, error)

GetIPTimezone returns the timezone for the specified IP.

func (*Client) SetCache

func (c *Client) SetCache(cache *Cache)

SetCache assigns a cache to the client `c`.

func (*Client) SetToken

func (c *Client) SetToken(token string)

SetToken assigns a token to the client `c`.

type Continent added in v2.9.1

type Continent struct {
	Code string `json:"code,omitempty" csv:"code"`
	Name string `json:"name,omitempty" csv:"name"`
}

type Core

type Core struct {
	IP              net.IP          `json:"ip" csv:"ip"`
	Hostname        string          `json:"hostname,omitempty" csv:"hostname" yaml:"hostname,omitempty"`
	Bogon           bool            `json:"bogon,omitempty" csv:"bogon" yaml:"bogon,omitempty"`
	Anycast         bool            `json:"anycast,omitempty" csv:"anycast" yaml:"anycast,omitempty"`
	City            string          `json:"city,omitempty" csv:"city" yaml:"city,omitempty"`
	Region          string          `json:"region,omitempty" csv:"region" yaml:"region,omitempty"`
	Country         string          `json:"country,omitempty" csv:"country" yaml:"country,omitempty"`
	CountryName     string          `json:"country_name,omitempty" csv:"country_name" yaml:"countryName,omitempty"`
	CountryFlag     CountryFlag     `json:"country_flag,omitempty" csv:"country_flag_,inline" yaml:"countryFlag,omitempty"`
	CountryFlagURL  string          `json:"country_flag_url,omitempty" csv:"country_flag_url" yaml:"countryFlagURL,omitempty"`
	CountryCurrency CountryCurrency `json:"country_currency,omitempty" csv:"country_currency_,inline" yaml:"countryCurrency,omitempty"`
	Continent       Continent       `json:"continent,omitempty" csv:"continent_,inline" yaml:"continent,omitempty"`
	IsEU            bool            `json:"isEU,omitempty" csv:"isEU" yaml:"isEU,omitempty"`
	Location        string          `json:"loc,omitempty" csv:"loc" yaml:"location,omitempty"`
	Org             string          `json:"org,omitempty" csv:"org" yaml:"org,omitempty"`
	Postal          string          `json:"postal,omitempty" csv:"postal" yaml:"postal,omitempty"`
	Timezone        string          `json:"timezone,omitempty" csv:"timezone" yaml:"timezone,omitempty"`
	ASN             *CoreASN        `json:"asn,omitempty" csv:"asn_,inline" yaml:"asn,omitempty"`
	Company         *CoreCompany    `json:"company,omitempty" csv:"company_,inline" yaml:"company,omitempty"`
	Carrier         *CoreCarrier    `json:"carrier,omitempty" csv:"carrier_,inline" yaml:"carrier,omitempty"`
	Privacy         *CorePrivacy    `json:"privacy,omitempty" csv:"privacy_,inline" yaml:"privacy,omitempty"`
	Abuse           *CoreAbuse      `json:"abuse,omitempty" csv:"abuse_,inline" yaml:"abuse,omitempty"`
	Domains         *CoreDomains    `json:"domains,omitempty" csv:"domains_,inline" yaml:"domains,omitempty"`
}

Core represents data from the Core API.

func GetIPInfo

func GetIPInfo(ip net.IP) (*Core, error)

GetIPInfo returns the details for the specified IP.

func GetIPInfoV6 added in v2.10.0

func GetIPInfoV6(ip net.IP) (*Core, error)

GetIPInfoV6 returns the details for the specified IPv6 IP.

type CoreASN

type CoreASN struct {
	ASN    string `json:"asn" csv:"id"`
	Name   string `json:"name" csv:"asn"`
	Domain string `json:"domain" csv:"domain"`
	Route  string `json:"route" csv:"route"`
	Type   string `json:"type" csv:"type"`
}

CoreASN represents ASN data for the Core API.

func GetIPASN

func GetIPASN(ip net.IP) (*CoreASN, error)

GetIPASN returns the ASN details for the specified IP.

type CoreAbuse

type CoreAbuse struct {
	Address     string `json:"address" csv:"address"`
	Country     string `json:"country" csv:"country"`
	CountryName string `json:"country_name" csv:"country_name"`
	Email       string `json:"email" csv:"email"`
	Name        string `json:"name" csv:"name"`
	Network     string `json:"network" csv:"network"`
	Phone       string `json:"phone" csv:"phone"`
}

CoreAbuse represents abuse data for the Core API.

func GetIPAbuse

func GetIPAbuse(ip net.IP) (*CoreAbuse, error)

GetIPAbuse returns the abuse details for the specified IP.

type CoreCarrier

type CoreCarrier struct {
	Name string `json:"name" csv:"name"`
	MCC  string `json:"mcc" csv:"mcc"`
	MNC  string `json:"mnc" csv:"mnc"`
}

CoreCarrier represents carrier data for the Core API.

func GetIPCarrier

func GetIPCarrier(ip net.IP) (*CoreCarrier, error)

GetIPCarrier returns the carrier details for the specified IP.

type CoreCompany

type CoreCompany struct {
	Name   string `json:"name" csv:"name"`
	Domain string `json:"domain" csv:"domain"`
	Type   string `json:"type" csv:"type"`
}

CoreCompany represents company data for the Core API.

func GetIPCompany

func GetIPCompany(ip net.IP) (*CoreCompany, error)

GetIPCompany returns the company details for the specified IP.

type CoreDomains

type CoreDomains struct {
	IP      string   `json:"ip" csv:"-"`
	Total   uint64   `json:"total" csv:"total"`
	Domains []string `json:"domains" csv:"-"`
}

CoreDomains represents domains data for the Core API.

func GetIPDomains

func GetIPDomains(ip net.IP) (*CoreDomains, error)

GetIPDomains returns the domains details for the specified IP.

type CorePrivacy

type CorePrivacy struct {
	VPN     bool   `json:"vpn" csv:"vpn"`
	Proxy   bool   `json:"proxy" csv:"proxy"`
	Tor     bool   `json:"tor" csv:"tor"`
	Relay   bool   `json:"relay" csv:"relay"`
	Hosting bool   `json:"hosting" csv:"hosting"`
	Service string `json:"service" csv:"service"`
}

CorePrivacy represents privacy data for the Core API.

func GetIPPrivacy

func GetIPPrivacy(ip net.IP) (*CorePrivacy, error)

GetIPPrivacy returns the privacy details for the specified IP.

type CountryCurrency added in v2.9.0

type CountryCurrency struct {
	Code   string `json:"code,omitempty" csv:"code"`
	Symbol string `json:"symbol,omitempty" csv:"symbol"`
}

type CountryFlag added in v2.9.0

type CountryFlag struct {
	Emoji   string `json:"emoji,omitempty" csv:"emoji"`
	Unicode string `json:"unicode,omitempty" csv:"unicode"`
}

type ErrorResponse

type ErrorResponse struct {
	// HTTP response that caused this error
	Response *http.Response

	// Error structure returned by the IPinfo Core API.
	Status string `json:"status"`
	Err    struct {
		Title   string `json:"title"`
		Message string `json:"message"`
	} `json:"error"`
}

An ErrorResponse reports an error caused by an API request.

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type IPMap added in v2.4.0

type IPMap struct {
	Status    string `json:"status"`
	ReportURL string `json:"reportUrl"`
}

IPMap is the full JSON response from the IP Map API.

func GetIPMap added in v2.4.0

func GetIPMap(ips []net.IP) (*IPMap, error)

GetIPMap returns an IPMap result for a group of IPs.

`len(ips)` must not exceed 500,000.

type IPSummary added in v2.3.0

type IPSummary struct {
	Total     uint64            `json:"total"`
	Unique    uint64            `json:"unique"`
	Countries map[string]uint64 `json:"countries"`
	Cities    map[string]uint64 `json:"cities"`
	Regions   map[string]uint64 `json:"regions"`
	ASNs      map[string]uint64 `json:"asns"`
	Companies map[string]uint64 `json:"companies"`
	IPTypes   map[string]uint64 `json:"ipTypes"`
	Routes    map[string]uint64 `json:"routes"`
	Carriers  map[string]uint64 `json:"carriers"`
	Mobile    uint64            `json:"mobile"`
	Domains   map[string]uint64 `json:"domains"`
	Privacy   struct {
		VPN     uint64 `json:"vpn"`
		Proxy   uint64 `json:"proxy"`
		Hosting uint64 `json:"hosting"`
		Relay   uint64 `json:"relay"`
		Tor     uint64 `json:"tor"`
	} `json:"privacy"`
	PrivacyServices map[string]uint64 `json:"privacyServices"`
	Anycast         uint64            `json:"anycast"`
	Bogon           uint64            `json:"bogon"`
}

IPSummary is the full JSON response from the IP summary API.

func GetIPSummary added in v2.3.0

func GetIPSummary(ips []net.IP) (*IPSummary, error)

GetIPSummary returns summarized results for a group of IPs.

type InvalidASNError

type InvalidASNError struct {
	ASN string
}

InvalidASNError is reported when the invalid ASN was specified.

func (*InvalidASNError) Error

func (err *InvalidASNError) Error() string

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL