ipdata

package module
v0.7.2 Latest Latest
Warning

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

 Go to latest Published: Oct 22, 2020 License: MIT Imports: 12 Imported by: 1

README

ipdata

License GoDoc Latest Git Tag Travis master Build Status Go Cover Test Coverage Go Report Card

Package ipdata is a client for the https://ipdata.co API. It provides functions for looking up data, as well as parsing the data in a programmatic way. The simplest usage is to build a new client and then use the Lookup method.

License

This code is released under the MIT License. Please see the LICENSE for the full content of the license.

Contributing

If you'd like to contribute to this project, I welcome any pull requests against this repo. The only ask is that a GitHub issue be opened detailing the desired functionality before making any pull requests.

Usage

The service provided by ipdata requires an API key before making API calls. Attempts to create a client without one will fail, as would attempts to contact the API. You can get an API key from https://ipdata.co/.

Here is a simple example of using the library:

import (
    "github.com/ipdata/go"
    "fmt"
)

ipd, _ := ipdata.NewClient("EXAMPLE_API_KEY")

data, err := ipd.Lookup("8.8.8.8")
if err != nil {
	// handle error
}

fmt.Printf("%s (%s)\n", data.IP, data.ASN)

Errors returned from the lookup function calls may be of type Error, which includes the message from the API and the HTTP status code. The Error() method on this type only returns the message and not the status code. To maintain compatibility with Go 1.12.x, this is still using github.com/pkg/errors for error management:

import "github.com/pkg/errors"

data, err := ipd.Lookup("8.8.8.8")
if err != nil {
	// do a type assertion on the error
	rerr, ok := errors.Cause(err).(ipdata.Error)

    if !ok {
    	// this wasn't a failure from rate limiting
    }
    
    fmt.Println("%d: %s", rerr.Code(), rerr.Error())
}

Contributors

  • Tim Heckman - Created the first version of this library

Documentation

Overview

Package ipdata is a client for the https://ipdata.co API. It provides functions for looking up data, as well as parsing the data in a programmatic way. The simplest usage is to build a new client and then use the Lookup method.

If you have any problems with this client, please raise an issue on GitHub:

* https://github.com/theckman/go-ipdata/issues

Example usage: 

import "github.com/theckman/go-ipdata"

ipd := ipdata.NewClient("") // API key is optional
data, err := ipd.Lookup("8.8.8.8")

Index

Constants

View Source 
const Version = "0.7.1"

Version is the package version

Variables

This section is empty.

Functions

This section is empty.

Types

type ASN added in v0.6.1 

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

ASN represents the Autonomous System Number data returned from the API.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the struct to represent the functionality presented by the https://ipdata.co API.

func NewClient 

func NewClient(apiKey string) (Client, error)

NewClient takes an optional API key and returns a Client. If you do not have an API key use an empty string ("").

func (*Client) BulkLookup added in v0.7.0 

func (c *Client) BulkLookup(ips []string) ([]*IP, error)

BulkLookup takes a set of IP addresses, and returns a set of results from the API. If the request failed, or something was wrong with one of the inputs, the error value will be of type Error. If err is non-nil, the []*IP slice may contain data (if it was able to process some of the inputs). The error value will contain the index of the first error in the bulk response.

Please note, any IPs that had a failed lookup will be a nil entry in the slice when an error is returned. So if you start to use the []*IP when err != nil, you will need to add explicit nil checks to avoid pointer derefence panics.

func (*Client) BulkLookupWithContext added in v0.7.2 

func (c *Client) BulkLookupWithContext(ctx context.Context, ips []string) ([]*IP, error)

BulkLookupWithContext is a BulkLookup with a provided context.Context.

func (Client) Lookup 

func (c Client) Lookup(ip string) (IP, error)

Lookup takes an IP address to look up the details for. An empty string means you want the information about the current node's pubilc IP address. If an API error occurs, the error value will be of type Error.

func (Client) LookupWithContext added in v0.7.2 

func (c Client) LookupWithContext(ctx context.Context, ip string) (IP, error)

LookupWithContext is a Lookup that uses a provided context.Context.

func (*Client) RawBulkLookup added in v0.7.0 

func (c *Client) RawBulkLookup(ips []string) (*http.Response, error)

RawBulkLookup takes a set of IP addresses, and returns the response from the API.

func (*Client) RawBulkLookupWithContext added in v0.7.2 

func (c *Client) RawBulkLookupWithContext(ctx context.Context, ips []string) (*http.Response, error)

RawBulkLookupWithContext is a RawBulkLookup with a provided context.Context.

func (Client) RawLookup added in v0.6.0 

func (c Client) RawLookup(ip string) (*http.Response, error)

RawLookup uses the internal mechanics to make an HTTP request to the API and returns the HTTP response. This allows consumers of the API to implement their own behaviors. If an API error occurs, the error value will be of type Error.

func (Client) RawLookupWithContext added in v0.7.2 

func (c Client) RawLookupWithContext(ctx context.Context, ip string) (*http.Response, error)

RawLookupWithContext is a RawLookup that uses a provided context.Context.

type Currency added in v0.5.0 

type Currency struct {
	Name   string `json:"name"`
	Code   string `json:"code"`
	Symbol string `json:"symbol"`
	Native string `json:"native"`
	Plural string `json:"plural"`
}

Currency represents the currency object within the JSON response from the API. This provides information about the currency where that IP resides.

type Error added in v0.6.0 

type Error struct {
	// contains filtered or unexported fields
}

Error represents an error returned from the ipdata.co API. This error value will be used whenever the HTTP request to the API completed, but the HTTP status code indicated failure. The Error() method will return the JSON message sent by the API, if present, and Code() returns the numeric HTTP status code.

func (Error) Code added in v0.6.0 

func (e Error) Code() int

Code returns the HTTP Status code returned from the ipdata.co API.

func (Error) Error added in v0.6.0 

func (e Error) Error() string

Error returns the message JSON field sent from the ipdata.co API. This also satisfies the error interface.

func (Error) Index added in v0.7.0 

func (e Error) Index() int

Index returns the index first item in a BulkLookup that encountered an error.

type IP 

type IP struct {
	IP           string `json:"ip"`
	ASN          ASN    `json:"asn"`
	Organization string `json:"organisation"`

	City       string `json:"city"`
	Region     string `json:"region"`
	RegionCode string `json:"region_code"`
	Postal     string `json:"postal"`

	CountryName string `json:"country_name"`
	CountryCode string `json:"country_code"`

	Flag         string `json:"flag"`
	EmojiFlag    string `json:"emoji_flag"`
	EmojiUnicode string `json:"emoji_unicode"`

	ContinentName string `json:"continent_name"`
	ContinentCode string `json:"continent_code"`

	Latitude  float64 `json:"latitude"`
	Longitude float64 `json:"longitude"`

	CallingCode string `json:"calling_code"`

	IsEU bool `json:"is_eu"`

	Languages []Language `json:"language,omitempty"`

	Currency *Currency `json:"currency,omitempty"`

	TimeZone *TimeZone `json:"time_zone,omitempty"`

	Threat *Threat `json:"threat,omitempty"`
}

IP is a struct that represents the JSON response from the https://ipdata.co API.

func (IP) String 

func (ip IP) String() string

type Language added in v0.5.0 

type Language struct {
	Name   string `json:"name"`
	Native string `json:"native"`
}

Language represents the language object within the JSON response from the API. This provides information about the language(s) where that IP resides.

type Threat added in v0.5.0 

type Threat struct {
	// IsTOR is true if the IP is associated with a node on the TOR (The Onion
	// Router) network
	IsTOR bool `json:"is_tor"`

	// IsProxy is true if the IP is associated with bring a proxy
	// (HTTP/HTTPS/SSL/SOCKS/CONNECT and transparent proxies)
	IsProxy bool `json:"is_proxy"`

	// IsAnonymous is true if either IsTor or IsProxy are true
	IsAnonymous bool `json:"is_anonymous"`

	// IsKnownAttacker is true if the IP address is a known source of malicious
	// activity (i.e. attacks, malware, botnet activity, etc)
	IsKnownAttacker bool `json:"is_known_attacker"`

	// IsKnownAbuser is true if the IP address is a known source of abuse
	// (i.e. spam, harvesters, registration bots, and other nuisance bots, etc)
	IsKnownAbuser bool `json:"is_known_abuser"`

	// IsThreat is true if either IsKnownAttacker or IsKnownAbuser are true
	IsThreat bool `json:"is_threat"`

	// IsBogon is true if this IP address should be within a bogon filter:
	// https://en.wikipedia.org/wiki/Bogon_filtering
	IsBogon bool `json:"is_bogon"`
}

Threat represents the threat object within the JSON response from the API. This provides information about what type of threat this IP may be.

type TimeZone added in v0.5.0 

type TimeZone struct {
	Name         string `json:"name"`
	Abbreviation string `json:"abbr"`
	Offset       string `json:"offset"`
	IsDST        bool   `json:"is_dst"`
	CurrentTime  string `json:"current_time,omitempty"`
}

TimeZone represents the time_zone object within the JSON response from the API. This provides information about the timezone where that IP resides.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.