ipdata

package module
v0.8.1 Latest Latest
Warning

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

 Go to latest Published: Feb 23, 2026 License: MIT Imports: 12 Imported by: 6

README

ipdata

CI Go Reference License Latest Git Tag Go Report Card

Package ipdata is a Go client for the ipdata.co API. It provides IP geolocation, threat intelligence, company detection, currency, timezone, carrier, and language data for any IP address.

Installation

go get github.com/ipdata/go

License

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

Usage

The service provided by ipdata requires an API key. You can get one from https://ipdata.co/.

Basic Lookup
package main

import (
	"fmt"

	"github.com/ipdata/go"
)

func main() {
	client, err := ipdata.NewClient("YOUR_API_KEY")
	if err != nil {
		panic(err)
	}

	data, err := client.Lookup("8.8.8.8")
	if err != nil {
		panic(err)
	}

	fmt.Printf("IP: %s\n", data.IP)
	fmt.Printf("Country: %s (%s)\n", data.CountryName, data.CountryCode)
	fmt.Printf("City: %s\n", data.City)
	fmt.Printf("ASN: %s (%s)\n", data.ASN.ASN, data.ASN.Name)

	if data.Company != nil {
		fmt.Printf("Company: %s\n", data.Company.Name)
	}

	if data.Threat != nil {
		fmt.Printf("VPN: %v, Tor: %v, Proxy: %v\n",
			data.Threat.IsVPN, data.Threat.IsTOR, data.Threat.IsProxy)
	}
}
EU Endpoint (GDPR Compliance)

For GDPR compliance, use NewEUClient to route all requests through EU data centers only (Frankfurt, Paris, and Ireland):

client, err := ipdata.NewEUClient("YOUR_API_KEY")
Field Filtering

Request only specific fields to reduce response size:

data, err := client.LookupFields("8.8.8.8", []string{"ip", "country_name", "threat"})
if err != nil {
	panic(err)
}

fmt.Printf("%s - %s\n", data.IP, data.CountryName)
Bulk Lookup

Look up multiple IPs in a single request:

results, err := client.BulkLookup([]string{"8.8.8.8", "1.1.1.1"})
if err != nil {
	// err may be of type ipdata.Error with index of first failure
	// results may still contain partial data
}

for _, ip := range results {
	if ip != nil {
		fmt.Printf("%s: %s\n", ip.IP, ip.CountryName)
	}
}
Error Handling

Errors returned from lookup functions may be of type Error, which includes the message from the API and the HTTP status code:

import "github.com/pkg/errors"

data, err := client.Lookup("8.8.8.8")
if err != nil {
	if apiErr, ok := errors.Cause(err).(ipdata.Error); ok {
		fmt.Printf("API error %d: %s\n", apiErr.Code(), apiErr.Error())
	}
}

Response Fields

The IP struct includes all fields from the ipdata API response:

Field Type Description
IP string IP address
City string City name
Region string Region/state name
RegionCode string ISO 3166-2 region code
CountryName string Country name
CountryCode string ISO 3166-1 alpha-2 code
ContinentName string Continent name
ContinentCode string 2-letter continent code
Latitude float64 Geographic latitude
Longitude float64 Geographic longitude
Postal string Postal/zip code
CallingCode string International calling code
Flag string URL to country flag image
EmojiFlag string Flag emoji character
EmojiUnicode string Unicode representation
IsEU bool Whether in the EU
Organization string Organization name
ASN ASN Autonomous System Number data
Company *Company Company/organization data
Carrier *Carrier Mobile carrier data
Languages []Language Languages spoken
Currency *Currency Local currency info
TimeZone *TimeZone Timezone info
Threat *Threat Threat intelligence data
Count string API request count (24h)
Status int HTTP status code
Nested Types

Company: Name, Domain, Network, Type

ASN: ASN, Name, Domain, Route, Type

Carrier: Name, MCC, MNC

Language: Name, Native, Code

Currency: Name, Code, Symbol, Native, Plural

TimeZone: Name, Abbreviation, Offset, IsDST, CurrentTime

Threat: IsTOR, IsVPN, IsICloudRelay, IsProxy, IsDatacenter, IsAnonymous, IsKnownAttacker, IsKnownAbuser, IsThreat, IsBogon, Blocklists, Scores

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.8.0"

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 Blocklist added in v0.8.0 

type Blocklist struct {
	Name string `json:"name"`
	Site string `json:"site"`
	Type string `json:"type"`
}

type Carrier added in v0.8.0 

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

Carrier represents the carrier 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, opts ...Option) (Client, error)

NewClient takes an API key and optional Options, and returns a Client that uses the default endpoint (https://api.ipdata.co/).

func NewEUClient added in v0.8.0 

func NewEUClient(apiKey string, opts ...Option) (Client, error)

NewEUClient takes an API key and optional Options, and returns a Client that uses the EU endpoint (https://eu-api.ipdata.co/). This ensures that all requests are routed through EU data centers only (Frankfurt, Paris, Ireland), which can be useful for GDPR compliance.

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) LookupFields added in v0.8.0 

func (c Client) LookupFields(ip string, fields []string) (IP, error)

LookupFields takes an IP address and a list of fields to return. Only the specified fields will be populated in the response. If an API error occurs, the error value will be of type Error.

func (Client) LookupFieldsWithContext added in v0.8.0 

func (c Client) LookupFieldsWithContext(ctx context.Context, ip string, fields []string) (IP, error)

LookupFieldsWithContext is a LookupFields that uses a provided context.Context.

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 Company added in v0.8.0 

type Company struct {
	Name    string `json:"name"`
	Domain  string `json:"domain"`
	Network string `json:"network"`
	Type    string `json:"type"`
}

Company represents the company object within the JSON response from the API. This provides information about the company that owns the IP address.

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:"languages,omitempty"`

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

	Carrier *Carrier `json:"carrier,omitempty"`

	Company *Company `json:"company,omitempty"`

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

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

	Count  string `json:"count,omitempty"`
	Status int    `json:"status,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"`
	Code   string `json:"code"`
}

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

type Option added in v0.8.1 

type Option func(*Client)

Option is a functional option for configuring the Client.

func WithHTTPClient added in v0.8.1 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the underlying *http.Client used by the Client. This allows callers to configure custom timeouts, proxies, transports, or instrument the client with tracing (e.g. OpenTelemetry).

type Scores added in v0.8.0 

type Scores struct {
	VPNScore    int `json:"vpn_score"`
	ProxyScore  int `json:"proxy_score"`
	ThreatScore int `json:"threat_score"`
	TrustScore  int `json:"trust_score"`
}

type Threat added in v0.5.0 

type Threat struct {
	IsTOR           bool        `json:"is_tor"`
	IsVPN           bool        `json:"is_vpn"`
	IsICloudRelay   bool        `json:"is_icloud_relay"`
	IsProxy         bool        `json:"is_proxy"`
	IsDatacenter    bool        `json:"is_datacenter"`
	IsAnonymous     bool        `json:"is_anonymous"`
	IsKnownAttacker bool        `json:"is_known_attacker"`
	IsKnownAbuser   bool        `json:"is_known_abuser"`
	IsThreat        bool        `json:"is_threat"`
	IsBogon         bool        `json:"is_bogon"`
	Blocklists      []Blocklist `json:"blocklists"`
	Scores          Scores      `json:"scores"`
}

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.