GeoIP2 and GeoLite2 Web Services Documentation

Overview

To learn more about the GeoIP2 Precision services and to purchase credits, please view our GeoIP2 Precision Services page.

If you are interested in minFraud Insights or minFraud Factors web services, which also contain GeoIP2 Precision Insights data, please contact our Enterprise Business team for assistance. To better understand the differences between each minFraud service, review our minFraud Service Comparison page and the Response Body section below.

API Clients

Official API Clients

Language or Framework

Package Repository

Documentation

Version Control

.NET (C#)

NuGet

GitHub Pages

Github

Java

Maven Central

GitHub Pages

Github

JavaScript (browser)

API Docs

Node.js

NPM

GitHub Pages

GitHub

Perl (deprecated)

CPAN

MetaCPAN

GitHub

PHP

Packagist

GitHub Pages

GitHub

Python

PyPI

Read the Docs

GitHub

Ruby

RubyGems

RubyDoc

GitHub

Third-Party API Clients

Use at your own risk. MaxMind does not offer support for these APIs and has not reviewed the code.

Language or Framework

Package Repository

Documentation

Version Control

Go

GoDoc

GitHub

Command Line (curl) Examples

The web service may be accessed using curl, a simple command-line HTTP client. The -u flag is used to pass the HTTP basic authentication header that provides the web service with your credentials.

For the following examples, replace {account_id} and {license_key} (including the brackets) with your account ID and license key, and replace {ip_address} with the IP address you wish to look up.

IP Geolocation Accuracy

IP Geolocation Usage

IP geolocation is inherently imprecise. Locations are often near the center of the population. Any location provided by a GeoIP database should not be used to identify a particular address or household.

Use the Accuracy Radius as an indication of geolocation accuracy for the latitude and longitude coordinates we return for an IP address. The actual location of the IP address is likely within the area defined by this radius and the latitude and longitude coordinates.

Versioning

The GeoIP2 Precision web services use two part versions. Our current release is version 2.1. The major version number will remain at 2 for the foreseeable future and will not change unless we are releasing an entirely new product ("GeoIP3").

The minor version will only change if there are breaking changes in the web service. A breaking change is one that breaks client code that follows the documentation on this page. Breaking changes include changing the type of an existing field, deleting a field entirely, or changing URIs.

All changes to the web services will be documented in the GeoIP2 release notes, whether or not the version number is changed.

The following changes are not considered to be breaking changes and will not be accompanied by a version number change:

  • Adding a new field, either at the top level of the structure or in one particular object such as the country or city. Client code should be written to allow for new fields to appear.
  • Adding new values to enum fields such as user_type. Note that this also applies to fields such as country codes, country subdivision codes, time zones, etc.
  • Adding a new language for localized names. We may add additional locale codes in the future.
  • Adding or removing error codes, and/or changing the body type for an error. Client code should always check the Content-Type header for any error response. Client code should also be prepared to handle any valid HTTP 4xx or 5xx status code.
  • Adding a new service. If we add a GeoIP2 Inter-Galactic service, we will use a new path such as /geoip/v2.1/inter-galactic. This should not break any existing client code.

This page was last updated on September 17, 2021.