geoip

package module
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: May 12, 2020 License: Apache-2.0 Imports: 15 Imported by: 0

README

go-geoip

Go Report Card Documentation license GitHub version GitHub issues

This is a wrapper around the GeoIP databases from MaxMind.

It also has a web API which automatically keeps the GeoIP database up-to-date. This is a very handy tool when you use e.g. a microservice approach and you don't want to keep a copy of the database for each microservice which needs GeoIP capabilities. By using the server approach, you can keep this functionality in a central place.

Building

make build-server

Building docker image

make build-docker-image

Running manually

PORT=8080 GEOIP_DB=testdata/GeoLite2-City.mmdb LICENSE_KEY=license ./geoip-server

Running via docker

The docker image automatically includes a copy of the GeoLite2-City.mmdb database.

docker run --rm pieterclaerhout/geoip-server

Using the server

$ curl "http://localhost:8080/lookup?ip=1.1.1.1"
{
  "IPAddress": "1.1.1.1",
  "Continent": {
    "ISOCode": "OC",
    "Names": {
      "de": "Ozeanien",
      "en": "Oceania",
      "es": "Oceanía",
      "fr": "Océanie",
      "ja": "オセアニア",
      "pt-BR": "Oceania",
      "ru": "Океания",
      "zh-CN": "大洋洲"
    }
  },
  "Country": {
    "ISOCode": "AU",
    "Names": {
      "de": "Australien",
      "en": "Australia",
      "es": "Australia",
      "fr": "Australie",
      "ja": "オーストラリア",
      "pt-BR": "Austrália",
      "ru": "Австралия",
      "zh-CN": "澳大利亚"
    }
  },
  "Location": {
    "Latitude": -33.494,
    "Longitude": 143.2104,
    "TimeZone": "Australia/Sydney"
  },
  "Subdivisions": null,
  "IsCached": false
}

Using the client

package main

import (
    "fmt"
    "os"
    "time"
    "github.com/pieterclaerhout/go-geoip"
)

func main() {

    client := geoip.NewClient("http://localhost:8080/  lookup", 5*time.Second)
  
    actual, err := client.Lookup("1.1.1.1")
    if err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
  
    fmt.Printf("%v\n", actual)

}

About the license key

To run the GeoIP server and use the automatic database download, you need to obtain a license key from MaxMind as explained here.

It's an easy and straightforward process:

  1. Sign up for a MaxMind account (no purchase required)

  2. Set your password and create a license key

  3. Use the environment variable LICENSE_KEY to set the license key which needs to be used.

Documentation

Index

Constants

View Source 
const DefaultChecksumExt = ".sha256"

DefaultChecksumExt is the default extension for the local checksum

View Source 
const DefaultChecksumURL = "https://download.maxmind.com/app/geoip_download?suffix=tar.gz.sha256"

DefaultChecksumURL is the URL where to download the checksum file

View Source 
const DefaultDownloadURL = "https://download.maxmind.com/app/geoip_download?suffix=tar.gz"

DefaultDownloadURL is the URL where to download the tgz file

Variables

This section is empty.

Functions

func CountryCodeToName 

func CountryCodeToName(code string) (string, error)

CountryCodeToName translates an ISO country to the English name

func CountryCodeToRegion 

func CountryCodeToRegion(code string) string

CountryCodeToRegion translates an ISO country code to a region Defaults to "west-europe"

func CountryNameToCode 

func CountryNameToCode(name string) (string, error)

CountryNameToCode translates the country name to it's ISO country code

Types

type Client 

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

Client is used to get the results from the server API

func NewClient 

func NewClient(url string, timeout time.Duration) *Client

NewClient returns a new Client instance with the given URL

func (*Client) ClearCache 

func (client *Client) ClearCache()

ClearCache clears the cache for the lookups

func (*Client) CountryCode 

func (client *Client) CountryCode(ipaddress string) (string, error)

CountryCode returns the country code for a specific IP address

func (*Client) CountryName 

func (client *Client) CountryName(ipaddress string) (string, error)

CountryName returns the country name for a specific IP address

func (*Client) Lookup 

func (client *Client) Lookup(ipaddress string) (*IPLocation, error)

Lookup returns the full country information for a specific IP address

func (*Client) RegionName 

func (client *Client) RegionName(ipaddress string) (string, error)

RegionName returns the region name for a specific IP address

Region can be: - west-us - south-brazil - japan-east - southeast-asia - west-europe (the default)

func (*Client) TimeZone 

func (client *Client) TimeZone(ipaddress string) (string, error)

TimeZone returns the timezone for a specific IP address

type Continent 

type Continent struct {
	ISOCode string            `maxminddb:"code"`  // The continent code
	Names   map[string]string `maxminddb:"names"` // The names for this continent
}

Continent defines the continent information for an IP location

type Country 

type Country struct {
	ISOCode string            `maxminddb:"iso_code"` // The ISO country code
	Names   map[string]string `maxminddb:"names"`    // The names for this country
}

Country defines the country information for an IP location

type Database 

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

Database is the main wrapper around the MaxMind GeoIP database

func NewDatabase 

func NewDatabase(path string) *Database

NewDatabase returns a new Database instance with the given database path

func (*Database) ClearCache 

func (database *Database) ClearCache()

ClearCache clears the cache for the lookups

func (*Database) CountryCode 

func (database *Database) CountryCode(ipaddress string) (string, error)

CountryCode returns the country code for a specific IP address

func (*Database) CountryName 

func (database *Database) CountryName(ipaddress string) (string, error)

CountryName returns the country name for a specific IP address

func (*Database) Lookup 

func (database *Database) Lookup(ipaddress string) (*IPLocation, error)

Lookup returns the full country information for a specific IP address

func (*Database) RegionName 

func (database *Database) RegionName(ipaddress string) (string, error)

RegionName returns the region name for a specific IP address

Region can be: - west-us - south-brazil - japan-east - southeast-asia - west-europe (the default)

func (*Database) TimeZone 

func (database *Database) TimeZone(ipaddress string) (string, error)

TimeZone returns the timezone for a specific IP address

type DatabaseDownloader 

type DatabaseDownloader struct {
	LicenseKey     string // The license key to use for the downloads
	TargetFilePath string // The path where to store the database

	DownloadURL string // The URL where to download the tgz file
	ChecksumURL string // The URL where to download the remote checksum
	// contains filtered or unexported fields
}

DatabaseDownloader is a struct used to download the GeoLite database from maxmind

func NewDatabaseDownloader 

func NewDatabaseDownloader(licenseKey string, targetFilePath string, timeout time.Duration) *DatabaseDownloader

NewDatabaseDownloader returns a new DatabaseDownloader instance configured with the default URLs

func (*DatabaseDownloader) Download 

func (downloader *DatabaseDownloader) Download() error

Download performs the actual download of the database

func (*DatabaseDownloader) LocalChecksum 

func (downloader *DatabaseDownloader) LocalChecksum() (string, error)

LocalChecksum returns the local checksum if any

func (*DatabaseDownloader) RemoteChecksum 

func (downloader *DatabaseDownloader) RemoteChecksum() (string, error)

RemoteChecksum returns the remote checksum

func (*DatabaseDownloader) ShouldDownload 

func (downloader *DatabaseDownloader) ShouldDownload() (bool, error)

ShouldDownload checks if a download is needed or not

It does this by comparing the local and remote checksum. If they are different, a download is needed

type GPSCoordinate 

type GPSCoordinate struct {
	Latitude  float64 `maxminddb:"latitude"`  // The latitude for this location
	Longitude float64 `maxminddb:"longitude"` // The longitude for this location
}

GPSCoordinate defines a GPS coordinate

type IPLocation 

type IPLocation struct {
	IPAddress    string
	Continent    *Continent     `maxminddb:"continent"`
	Country      *Country       `maxminddb:"country"`
	Location     *Location      `maxminddb:"location"`
	Subdivisions []*Subdivision `maxminddb:"subdivisions"`
	IsCached     bool
}

IPLocation defines all info we know about a location based on it's IP address

func (*IPLocation) ApproximateGPSCoordinate 

func (ipLocation *IPLocation) ApproximateGPSCoordinate() *GPSCoordinate

ApproximateGPSCoordinate returns the GPS coordinates for the location

func (*IPLocation) ContinentCode 

func (ipLocation *IPLocation) ContinentCode() string

ContinentCode returns the ISO country code for the location

func (*IPLocation) ContinentName 

func (ipLocation *IPLocation) ContinentName() string

ContinentName returns the country name for the location in English

func (*IPLocation) CountryCode 

func (ipLocation *IPLocation) CountryCode() string

CountryCode returns the ISO country code for the location

func (*IPLocation) CountryName 

func (ipLocation *IPLocation) CountryName() string

CountryName returns the country name for the location in English

func (*IPLocation) RegionName 

func (ipLocation *IPLocation) RegionName() string

RegionName returns the region name for the location in English

func (*IPLocation) SubdivisionCodes 

func (ipLocation *IPLocation) SubdivisionCodes() []string

SubdivisionCodes returns the codes for the subdivisions

func (*IPLocation) SubdivisionNames 

func (ipLocation *IPLocation) SubdivisionNames() []string

SubdivisionNames returns the names for the subdivisions

func (*IPLocation) TimeZone 

func (ipLocation *IPLocation) TimeZone() string

TimeZone returns the timezone for the location

type Location 

type Location struct {
	GPSCoordinate
	TimeZone string `maxminddb:"time_zone"` // The timezone for this location
}

Location defines all the location information we know such as timezone, lat and lon

type Subdivision 

type Subdivision struct {
	ISOCode string            `maxminddb:"iso_code"` // The ISO subdivision code
	Names   map[string]string `maxminddb:"names"`    // The names for this subdivision
}

Subdivision defines a subdivision of the country (state, province)

Source Files

View all Source files

Directories

Path Synopsis
cmd
db-downloader
geoip-server
geoip-server/core
geoip-server/geoip
scripts
post_build
pre_build

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.