Geolocate an IP address using Databases

Geolocating an IP address using GeoIP2 and GeoLite2 databases consists of configuring a database reader and querying the database.

Implementation

MaxMind offers and highly recommends using official client libraries to query our databases.

1. Install the GeoIP2 client library

We have a collection of officially supported libraries for you to query with the GeoIP2 and GeoLite2 databases:

1// Install via NuGet
2Install-Package MaxMind.GeoIP2

 1// Install via Maven, recommended
 2<dependency>
 3  <groupId>com.maxmind.geoip2</groupId>
 4  <artifactId>geoip2</artifactId>
 5  <version>2.15.0</version>
 6</dependency>
 7
 8// Or install via Gradle
 9repositories {
10  mavenCentral()
11}
12dependencies {
13  compile 'com.maxmind.geoip2:geoip2:2.15.0'
14}

1// Install via npm
2npm install @maxmind/geoip2-node
3
4// Or install via yarn
5yarn add @maxmind/geoip2-node

1# Install via Composer
2composer require geoip2/geoip2:~2.0

1# Install via pip
2pip install geoip2

1# Install as a gem
2gem install maxmind-geoip2
3
4# Or add this to your Gemfile
5gem 'maxmind-geoip2'

2. Configure a GeoIP2 database reader to query the database

Configuring the database reader requires the database file to be accessible on the filesystem. After configuring the database reader, you can then query the database by calling the method corresponding to the database type (e.g. city or country) and passing it the IP address you want to look up.

If the lookup succeeds, the method call will return a model class/object for the database method you called. This model in turn contains multiple record classes/objects, each of which represents part of the data for the record.

If the request fails, the reader class will throw an exception or return an error depending on the library.

For more details on database methods, errors, and exceptions, see the client API documentation below.

1using (var reader = new DatabaseReader("path/to/maxmind-database.mmdb"))
2{
3    var response = reader.City("128.101.101.101");
4
5    Console.WriteLine(response.Country.IsoCode);
6}

 1File database = new File("/path/to/maxmind-database.mmdb")
 2
 3// This reader object should be reused across lookups as creation of it is
 4// expensive.
 5DatabaseReader reader = new DatabaseReader.Builder(database).build();
 6
 7// If you want to use caching at the cost of a small (~2MB) memory overhead:
 8// new DatabaseReader.Builder(file).withCache(new CHMCache()).build();
 9
10InetAddress ipAddress = InetAddress.getByName("128.101.101.101");
11
12CityResponse response = reader.city(ipAddress);
13
14Country country = response.getCountry();
15System.out.println(country.getIsoCode());

 1// Asynchronous database opening
 2const Reader = require('@maxmind/geoip2-node').Reader;
 3
 4Reader.open('/path/to/maxmind-database.mmdb').then(reader => {
 5  const response = reader.city('128.101.101.101');
 6
 7  console.log(response.country.isoCode);
 8});
 9
10
11// Synchronous database opening
12const fs = require('fs');
13const Reader = require('@maxmind/geoip2-node').Reader;
14
15const dbBuffer = fs.readFileSync('/path/to/maxmind-database.mmdb');
16
17// This reader object should be reused across lookups as creation of it is
18// expensive.
19const reader = Reader.openBuffer(dbBuffer);
20
21response = reader.city('128.101.101.101');
22
23console.log(response.country.isoCode);

 1<?php
 2require_once 'vendor/autoload.php';
 3use GeoIp2\Database\Reader;
 4
 5// This reader object should be reused across lookups as creation of it is
 6// expensive.
 7$reader = new Reader('/path/to/maxmind-database.mmdb');
 8
 9$record = $reader->city('128.101.101.101');
10
11print($record->country->isoCode);

1import geoip2.database
2
3# This reader object should be reused across lookups as creation of it is
4# expensive.
5with geoip2.database.Reader('/path/to/maxmind-database.mmdb') as reader:
6    response = reader.city('128.101.101.101');
7    print(response.country.iso_code)

1require 'maxmind/geoip2'
2
3# This reader object should be reused across lookups as creation of it is
4# expensive.
5reader = MaxMind::GeoIP2::Reader.new('/path/to/maxmind-database.mmdb')
6
7record = reader.city('128.101.101.101')
8
9puts record.country.iso_code

APIs and Third-Party Integrations

You can find a complete list of official and unofficial client APIs, and third-party integrations on the database documentation page.