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.

Expand ▾ Collapse ▴

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)