IPGeolocation Go SDK

Overview

Official Go SDK for the IPGeolocation.io IP Location API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data from one API.

• Go module with v2 import path
• Typed responses plus raw JSON and XML methods
• Built on the Go standard library

Install

go get github.com/IPGeolocation/ip-geolocation-go-sdk/v2

import ipgeolocation "github.com/IPGeolocation/ip-geolocation-go-sdk/v2"

Go module: github.com/IPGeolocation/ip-geolocation-go-sdk/v2 Package page: https://pkg.go.dev/github.com/IPGeolocation/ip-geolocation-go-sdk/v2 GitHub repository: https://github.com/IPGeolocation/ip-geolocation-go-sdk

Quick Start

package main

import (
	"context"
	"fmt"
	"os"

	ipgeolocation "github.com/IPGeolocation/ip-geolocation-go-sdk/v2"
)

func main() {
	apiKey := os.Getenv("IPGEO_API_KEY")
	if apiKey == "" {
		panic("set IPGEO_API_KEY first")
	}

	client, err := ipgeolocation.NewClient(&ipgeolocation.Config{
		APIKey: apiKey,
	})
	if err != nil {
		panic(err)
	}
	defer client.Close()

	response, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
		IP: "8.8.8.8",
	})
	if err != nil {
		panic(err)
	}

	data := response.Data

	if data.IP != nil {
		fmt.Println(*data.IP) // 8.8.8.8
	}

	if data.Location != nil && data.Location.CountryName != nil {
		fmt.Println(*data.Location.CountryName) // United States
	}

	if data.Location != nil && data.Location.City != nil {
		fmt.Println(*data.Location.City)
	}

	if data.TimeZone != nil && data.TimeZone.Name != nil {
		fmt.Println(*data.TimeZone.Name)
	}

	if response.Metadata.CreditsCharged != nil {
		fmt.Println(*response.Metadata.CreditsCharged)
	}
}

At a Glance

Get Your API Key

Create an IPGeolocation account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

Create a client with NewClient . Config values are validated when the client is created. Request values are validated before each request is sent.

Available Methods

Request Options

Examples

The examples below assume you already have a configured client in scope:

apiKey := os.Getenv("IPGEO_API_KEY")

client, err := ipgeolocation.NewClient(&ipgeolocation.Config{
	APIKey: apiKey,
})
if err != nil {
	panic(err)
}
defer client.Close()

response, err := client.LookupIPGeolocation(context.Background(), nil)
if err != nil {
	panic(err)
}

if response.Data.IP != nil {
	fmt.Println(*response.Data.IP)
}

response, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
	IP: "ipgeolocation.io",
})
if err != nil {
	panic(err)
}

if response.Data.Domain != nil {
	fmt.Println(*response.Data.Domain) // ipgeolocation.io
}

response, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
	IP:      "9.9.9.9",
	Include: []string{"security", "abuse"},
})
if err != nil {
	panic(err)
}

if response.Data.Security != nil && response.Data.Security.ThreatScore != nil {
	fmt.Println(*response.Data.Security.ThreatScore)
}

if response.Data.Abuse != nil && len(response.Data.Abuse.Emails) > 0 {
	fmt.Println(response.Data.Abuse.Emails[0])
}

visitorUA := "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"

response, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
	IP:      "115.240.90.163",
	Include: []string{"user_agent"},
	Headers: map[string]string{
		"User-Agent": visitorUA,
	},
})
if err != nil {
	panic(err)
}

if response.Data.UserAgent != nil && response.Data.UserAgent.Name != nil {
	fmt.Println(*response.Data.UserAgent.Name)
}

response, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
	IP:       "8.8.8.8",
	Include:  []string{"security"},
	Fields:   []string{"location.country_name", "security.threat_score", "security.is_vpn"},
	Excludes: []string{"currency"},
})
if err != nil {
	panic(err)
}

if response.Data.Location != nil && response.Data.Location.CountryName != nil {
	fmt.Println(*response.Data.Location.CountryName)
}

if response.Data.Security != nil && response.Data.Security.IsVPN != nil {
	fmt.Println(*response.Data.Security.IsVPN)
}

fmt.Println(response.Data.Currency == nil)

response, err := client.LookupIPGeolocationRaw(context.Background(), &ipgeolocation.LookupRequest{
	IP:     "8.8.8.8",
	Output: ipgeolocation.ResponseFormatXML,
})
if err != nil {
	panic(err)
}

fmt.Println(response.Data)

response, err := client.BulkLookupIPGeolocation(context.Background(), &ipgeolocation.BulkLookupRequest{
	IPs: []string{"8.8.8.8", "1.1.1.1"},
})
if err != nil {
	panic(err)
}

for _, result := range response.Data {
	if result.IsSuccess() && result.Data != nil && result.Data.IP != nil {
		fmt.Println(*result.Data.IP)
		continue
	}

	if result.Error != nil {
		fmt.Println(result.Error.Message)
	}
}

response, err := client.BulkLookupIPGeolocationRaw(context.Background(), &ipgeolocation.BulkLookupRequest{
	IPs: []string{"8.8.8.8", "1.1.1.1"},
})
if err != nil {
	panic(err)
}

fmt.Println(response.Data)

Response Metadata

Every method returns APIResponse[T] , where:

• Data contains the typed object or raw response string
• Metadata contains response details such as:
  • CreditsCharged
  • SuccessfulRecords
  • StatusCode
  • DurationMS
  • RawHeaders

Example:

fmt.Println(response.Metadata.StatusCode)
fmt.Println(response.Metadata.DurationMS)
fmt.Println(response.Metadata.FirstHeaderValue("content-type"))

Errors

The SDK returns typed errors instead of leaving you to parse error bodies yourself.

*APIError has status-specific types:

• *BadRequestError
• *UnauthorizedError
• *ForbiddenError
• *NotFoundError
• *MethodNotAllowedError
• *ContentTooLargeError
• *UnsupportedMediaTypeError
• *LockedError
• *TooManyRequestsError
• *CustomStatus499Error
• *InternalServerError

Example:

var validationErr *ipgeolocation.ValidationError

_, err := client.LookupIPGeolocation(context.Background(), &ipgeolocation.LookupRequest{
	Output: ipgeolocation.ResponseFormatXML,
})
if err != nil {
	if errors.As(err, &validationErr) {
		fmt.Println(validationErr.Message)
		return
	}

	fmt.Println(err)
}

Troubleshooting

• Bulk lookup always requires APIKey . RequestOrigin is not enough.
• Typed methods only support JSON. Use the raw methods for XML.
• If you need security, abuse, user-agent, or hostname data, include those modules explicitly.
• Fields and Excludes filter the response. They do not unlock paid data.
• RequestOrigin must be an origin only. Do not include a path, query string, fragment, or userinfo.
• Response fields are pointers so omitted fields stay omitted.

Frequently Asked Questions

Only for single lookup with paid-plan request-origin auth. Bulk lookup always requires an API key.

No. Typed methods only support JSON. Use LookupIPGeolocationRaw or BulkLookupIPGeolocationRaw for XML.

Pointers let the SDK preserve omitted fields instead of inventing zero values for data the API did not send.

No. Domain lookup is a paid-plan feature.

Links

• Homepage: https://ipgeolocation.io
• IP Location API product page: https://ipgeolocation.io/ip-location-api.html
• Documentation: https://ipgeolocation.io/documentation/ip-location-api.html
• Go package: https://pkg.go.dev/github.com/IPGeolocation/ip-geolocation-go-sdk/v2
• GitHub repository: https://github.com/IPGeolocation/ip-geolocation-go-sdk