ip2location-go: a file-based IP geolocation lookup for Go services

A local database file, not a web service

The IP2Location Go package provides a fast lookup of a long list of fields from an IP address, using an IP2Location database that is downloaded as a file.

That distinction is the whole design. The readme describes the database as simply containing IP blocks as keys, and other information such as country, region, city, latitude, longitude, ZIP code, time zone, ISP, domain name, connection type, IDD code, area code, weather station code, station name, mcc, mnc, mobile brand, elevation, usage type, address type, IAB category, district, autonomous system number and autonomous system as values. The lookup is a local file read, not a request to somebody else's API, which means there is no per-lookup latency budget, no rate limit, no API key and no outbound traffic from your service.

The field list is worth reading as a list of decisions. Alongside the obvious geolocation fields it includes IDD code, area code, weather station code and station name, which are the pieces you need to place a phone call or look up weather for a location. It includes mcc and mnc and mobile brand, which identify the mobile carrier. It includes elevation, which some delivery and network routing decisions use. And it includes IAB category, address type, usage type and the AS fields, which are the ones that distinguish a hosting provider from a residential connection, which is what most abuse and fraud checks actually need.

The package supports both IPv4 and IPv6 addresses. The module path carries a major version suffix, /v9, and the go.mod file declares a Go 1.14 language version with one indirect dependency on lukechampine.com/uint128, which is the 128-bit integer type the IPv6 range arithmetic needs.

module github.com/ip2location/ip2location-go/v9

go 1.14

require lukechampine.com/uint128 v1.2.0 // indirect

The primary language is Go, the licence for the library is MIT with the terms in LICENSE.TXT, the default branch is master, and the last push was on 2026-07-22.

The use cases the fields were chosen for

The readme lists the kinds of projects the package is meant for, and it is worth reading them as a catalogue of decisions you would otherwise have to make yourself.

Selecting the geographically closest mirror is the first, and it needs only country or region plus coordinates to pick the nearest CDN edge rather than the geographically nearest. Analyzing web server logs to determine the countries of your visitors is the second, and it is the case where a local file matters most, because a log analysis job may process millions of rows and a network round trip per row would dominate the runtime.

Credit card fraud detection is the third, and it is where the usage type and the AS fields start to matter, because a transaction from a hosting provider's address is a different signal from one from a mobile carrier's network.

Software export controls is the fourth, and it is the most demanding of the list, because export control is a legal requirement rather than a heuristic, and it needs country plus a usage classification and the autonomous system to decide whether the traffic comes from an organisation rather than from a consumer.

The remaining three are display native language and currency, which needs country and region to pick a locale, prevent password sharing and abuse of service, which needs to detect the same account used from distant places, and geotargeting in advertisement.

Read together, they tell you what the data is for. The package is aimed at decisions that need to know a rough place and a rough kind of connection, not a precise address. That is consistent with an IP block database, where many addresses share a location, and it is the limit you should hold in mind: the answer for a given IP is the answer for the block it falls in, not for a device.

The database file is the real dependency, and it is licensed separately

The Go package is free and open source. The data it reads is not, and the arrangement is worth being explicit about before you plan an architecture around it.

The readme says the database will be updated on a monthly basis for greater accuracy, and that free LITE databases are available at lite.ip2location.com upon registration. The paid databases are available at ip2location.com under a Premium subscription package.

So the operational model is: subscribe or register, download a database file, keep it updated monthly, and ship it alongside your binary or mount it in your container. The monthly update is a recurring operational task rather than a one-off setup step, and if the file ages the accuracy of every answer degrades with it.

The field coverage differs by tier, and the readme does not enumerate which fields each tier includes. That is a question for the pricing page rather than the documentation, and it matters because the field list in the readme is a union. If your use is export controls, you need the autonomous system and usage fields; if your use is advertising geotargeting, you may need only country and city. Buying the wrong tier is an easy mistake that shows up as missing values at runtime.

The file-based approach has a second property that is easy to overlook and useful in restricted environments. Because the lookup is a local read, the package works in an air-gapped deployment, and the country, region and city fields are the ones a privacy-sensitive service is most likely to want. The readme notes that the database is a file that contains the data, which also means it can be inspected, versioned and audited, unlike the response of a hosted API.

The developer documentation is at ip2location-go.readthedocs.io, and it is there that the installation steps and the code examples live. The readme itself points to it rather than repeating it.

What the release history tells you about IPv6 and database versions

The recent release notes carry three pieces of information that matter for a production deployment.

v9.8.0, released on 2025-09-03, added support for AS domain, AS usage type and AS CIDR. That is an extension of the autonomous system fields, which are the ones used to distinguish hosting providers from access networks and to identify the operator of an address. So a v9.8.0 or later client can surface the domain an AS announces, how that AS is used, and its CIDR, which is the data a routing or abuse decision often needs.

v9.7.1, released on 2024-12-03, fixed an issue with an IPv6 IP when using an IPv4 BIN. The BIN is the binary format of the database file, so this is a concrete interoperability problem between the address family you query with and the data file you query against: an IPv6 address looked up in a database that only holds IPv4 blocks was mishandled. The fix tells you that mixing address families is supported but was not correct before that release, and it tells you to check your client version if you look up IPv6 addresses.

v9.7.0, released on 2024-01-11, added the PackageVersion and DatabaseVersion functions. Those two functions exist to answer the question of what you are running: which version of the library, and which version of the data file. That is exactly what you need when a lookup returns something unexpected and you need to know whether the client or the data is stale.

That last point is the one to take seriously. With a monthly data refresh and a separate client version, an answer that changed without you changing code is almost always a data update. Having both version numbers available lets you log them with every request, which turns a support question into a lookup.

The library files in the repository reflect that structure. country.go and region.go hold the country and region lookup logic, iptools.go holds the address handling, ip2location.go is the main entry point, and ip2locationwebservice.go is a separate client for the hosted web service, so the package covers both the file-based and the API-based access to the same data.

The file-based library against the web service and against a free API

Two alternatives are worth comparing, and the repository itself contains both halves of the first one.

The web service client, in ip2locationwebservice.go, talks to the hosted IP2Location API over the network. The difference in approach is exactly the file versus the request. The web service gives you a current database without managing one, and it gives the same fields without downloading a file you have to keep updated. The file gives you a lookup with no network dependency, no per-request cost and no rate limit, at the price of a monthly refresh task and a data file in your deployment.

For a service doing geotargeting on a handful of requests a second, the hosted API is simpler and you are not carrying a stale-data risk. For a log analysis job, a batch job, or a service in a network-restricted environment, the file is the only option that works at all.

The other alternative is a free IP geolocation API. The readme is blunt about why the free tier exists: the free LITE databases are available upon registration. A free hosted API is cheaper still but with the usual tradeoffs, accuracy is coarser and the free tiers change their limits.

What the IP2Location package offers against those is a specific combination: the same data you can get from the API, in a form you can license at a resolution that matches your use, plus the fields that a generic geolocation service often does not expose, such as the IAB category, the address type, the usage type, the area code and the mobile carrier details.

Those extra fields are the reason to look at this package at all if you are doing anything beyond a country lookup. A generic IP lookup tells you roughly where a connection is. This one tells you what kind of connection it is, which is the question behind most abuse detection and export control.

The honest limit is the same in every case: the answer is a property of the IP block, so it is wrong at the edges, and it is wrong for mobile connections where the address is not really a location at all. The readme's own list of use cases avoids those cases, and so should your use of it.

Editorial conclusion

ip2location-go fits a Go service that needs country or city level geolocation without adding a network dependency to every lookup, and it does not fit a project that needs street-level accuracy or that refuses to run a proprietary data file. Before adopting it, confirm which database tier you will licence, since the free LITE databases and the premium ones differ in the fields they contain, and check the release history for the IPv6 behaviour if you plan to look up IPv6 addresses against an IPv4 database file.

Frequently asked questions

Official sources

1. ip2location/ip2location-go on GitHub
2. License: MIT
3. Project website
4. README
5. Releases