README

PHP GeoIP

A lightweight PHP library for IP geolocation lookups and response formatting — one API across a zero-config remote service, MaxMind GeoLite2, DB-IP, IPLocate, IPinfo and IP2Location.

Features

• Zero config by default — works out of the box via the remote ip.serviss.it service, no database to download.
• Simple API — resolve an IP to a structured array with a single locate() call.
• Multiple data sources — the remote service, MaxMind GeoLite2, DB-IP, IPLocate, IPinfo (MMDB) and IP2Location (BIN), behind one provider interface.
• City & ASN data — country, region, city, coordinates, timezone, and the originating organisation.
• Flexible output — render results as JSON or plain text, or pluck a single attribute.
• Command line ready — a geoip binary for lookups straight from the shell.
• License-clean — ships no database; you supply your own for local lookups, and the library surfaces each source's required attribution.
• Lean dependencies — only the official geoip2/geoip2 reader. PHP 7.2+.

Table of contents

• Installation
• Obtaining a database
• Usage
• Database providers
• Result schema
• Error handling
• Command line
• Examples
• Requirements
• License & attribution

Installation

composer require ilmlv/php-geoip

Obtaining a database

You don't need one to get started: by default the library queries the remote ip.serviss.it service (see Database providers). For local, offline or high-volume lookups, use one of the database providers instead.

This package bundles no database — database licenses vary by source and most require keeping the data current. The included geoip-update downloader supports several sources:

# MaxMind GeoLite2 (free account + license key required)
MAXMIND_LICENSE_KEY=your_key vendor/bin/geoip-update --dir=./data

# DB-IP Lite — no API key, CC BY 4.0 (just attribute db-ip.com)
vendor/bin/geoip-update --source=dbip --dir=./data

# Any direct .mmdb / .mmdb.gz URL (e.g. an IPLocate or IPinfo tokenised link)
vendor/bin/geoip-update --source=url --url='https://…/file.mmdb.gz' --dir=./data

For scheduled MaxMind updates, the official geoipupdate tool is also a good option. See Database providers for which sources need a key and how to attribute them.

Usage

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\ResponseFormatter;

// Zero config: no argument → looks up via the remote ip.serviss.it service.
$locator = new GeoIpLocator();

// Or read a local MaxMind GeoLite2 (or compatible) database:
$locator = new GeoIpLocator(
    '/path/to/GeoLite2-City.mmdb',
    '/path/to/GeoLite2-ASN.mmdb'   // optional — enables the `organisation` field
);

$result = $locator->locate('8.8.8.8');

$formatter = new ResponseFormatter();
echo $formatter->toJson($result);                   // JSON string
echo $formatter->toPlainText($result);              // "Pretty-Key: value" lines
echo $formatter->pluck($result, 'country-iso-code'); // "US"

To include a country.flag.url in the result, pass a base URL as the third constructor argument:

$locator = new GeoIpLocator($cityDb, $asnDb, '//cdn.example.com/flags');

Database providers

By default (no constructor argument) the library uses the remote provider, which queries the public ip.serviss.it service — no database required. To read a local database instead, pass a provider to GeoIpLocator::withProvider(). Every provider returns the same result schema, so the rest of your code is unchanged.

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\Provider\ServissItProvider;
use IlmLV\GeoIp\Provider\MmdbCityProvider;
use IlmLV\GeoIp\Provider\IpinfoLiteProvider;
use IlmLV\GeoIp\Provider\IP2LocationProvider;

// Remote ip.serviss.it (default; equivalent to `new GeoIpLocator()`)
GeoIpLocator::withProvider(new ServissItProvider());

// MMDB family (MaxMind-reader compatible). Optional 2nd arg = ASN database.
GeoIpLocator::withProvider(MmdbCityProvider::dbip('data/dbip-city-lite.mmdb'));
GeoIpLocator::withProvider(MmdbCityProvider::iplocate('data/iplocate-city.mmdb'));
GeoIpLocator::withProvider(MmdbCityProvider::maxmind('data/GeoLite2-City.mmdb', 'data/GeoLite2-ASN.mmdb'));

// IPinfo Lite (flat MMDB schema — country/continent/ASN only)
GeoIpLocator::withProvider(new IpinfoLiteProvider('data/ipinfo-lite.mmdb'));

// IP2Location BIN (needs ip2location/ip2location-php; see Requirements)
GeoIpLocator::withProvider(new IP2LocationProvider('data/IP2LOCATION-LITE-DB11.BIN'));

$locator->attribution(); // the source's required attribution string, or null

The remote provider makes an outbound HTTPS call per lookup to a fixed endpoint (https://ip.serviss.it) and needs no database; it's ideal for getting started and low-volume use. For offline use, high volume, or to avoid sending IPs to a third party, choose a local provider. It throws RemoteException on a network/service failure.

† These sources require their attribution to be displayed wherever their data appears. GeoIpLocator::attribution() returns the exact snippet (the CLI prints it automatically; the web-endpoint example shows how to render it). See License & attribution.

Result schema

locate() returns a normalised array. Missing values are null.

[
    'ip'           => '8.8.8.8',
    'organisation' => 'GOOGLE',
    'city'         => ['name' => null],
    'country'      => [
        'name'                 => 'United States',
        'iso_code'             => 'US',
        'is_in_european_union' => false,
        'flag'                 => ['emoji' => '🇺🇸'],
    ],
    'continent'    => ['name' => 'North America', 'code' => 'NA'],
    'region'       => ['name' => null, 'iso_code' => null],
    'location'     => ['latitude' => 37.751, 'longitude' => -97.822],
    'zip_code'     => null,
    'time_zone'    => 'America/Chicago',
    'metro_code'   => null,
]

ResponseFormatter::pluck() accepts any nested or flattened key, case- and separator-insensitive — country-iso-code, country_iso_code, and country all resolve.

Error handling

All exceptions implement the IlmLV\GeoIp\Exception\GeoIpException marker interface, so the whole package can be caught in one block.

Command line

The package installs a geoip binary at vendor/bin/geoip for lookups from the shell. With no --provider, it uses the remote ip.serviss.it service (zero setup):

vendor/bin/geoip 8.8.8.8
vendor/bin/geoip 8.8.8.8 --format=json
vendor/bin/geoip 8.8.8.8 --what=country-iso-code   # → US

For a local database, pick a provider:

vendor/bin/geoip 8.8.8.8 --provider=mmdb --db=./data/GeoLite2-City.mmdb
vendor/bin/geoip 8.8.8.8 --provider=dbip --db=./data/dbip-city-lite.mmdb

Database paths default to ./data. Exit codes: 0 success, 1 usage/runtime error, 2 IP not found.

Examples

Short, copy-pasteable recipes. They use the zero-config remote provider unless a database path is given.

Look up an IP

use IlmLV\GeoIp\GeoIpLocator;

$result = (new GeoIpLocator())->locate('8.8.8.8');
echo $result['country']['name'];      // "United States"
echo $result['country']['iso_code'];  // "US"
echo $result['time_zone'];            // "America/Chicago"

Format the result

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\ResponseFormatter;

$result = (new GeoIpLocator())->locate('8.8.8.8');
$format = new ResponseFormatter();

echo $format->toJson($result);                    // JSON string
echo $format->toPlainText($result);               // "Country-Name: United States\n…"
echo $format->pluck($result, 'country-iso-code'); // "US"  (single field)

Read a local database

use IlmLV\GeoIp\GeoIpLocator;

// MaxMind GeoLite2 (City + optional ASN). Download with `vendor/bin/geoip-update`.
$result = (new GeoIpLocator('data/GeoLite2-City.mmdb', 'data/GeoLite2-ASN.mmdb'))
    ->locate('8.8.8.8');

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\Provider\MmdbCityProvider;

// DB-IP Lite (no API key). `attribution()` then returns the link you must show.
$locator = GeoIpLocator::withProvider(MmdbCityProvider::dbip('data/dbip-city-lite.mmdb'));
$result  = $locator->locate('8.8.8.8');
echo $locator->attribution(); // <a href='https://db-ip.com'>IP Geolocation by DB-IP</a>

Handle errors

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\Exception\GeoIpException;

try {
    $result = (new GeoIpLocator())->locate($ip);
} catch (GeoIpException $e) {
    // Covers invalid IP, address-not-found and remote failures in one catch.
    echo 'Lookup failed: ' . $e->getMessage();
}

A complete web endpoint

Save as public/index.php and run php -S localhost:8080 -t public. It supports ?ip=, ?format=json|plain (default plain) and ?what= for a single field:

GET /?ip=8.8.8.8                       → plain text
GET /?ip=8.8.8.8&format=json           → JSON
GET /?ip=8.8.8.8&what=country-iso-code → "US"

<?php
require __DIR__ . '/../vendor/autoload.php';

use IlmLV\GeoIp\GeoIpLocator;
use IlmLV\GeoIp\ResponseFormatter;
use IlmLV\GeoIp\Exception\GeoIpException;

$ip     = $_GET['ip']     ?? ($_SERVER['REMOTE_ADDR'] ?? '');
$format = $_GET['format'] ?? 'plain';
$what   = $_GET['what']   ?? null;

$formatter = new ResponseFormatter();

try {
    $result = (new GeoIpLocator())->locate($ip);
    $value  = $what !== null ? $formatter->pluck($result, $what) : $result;
} catch (GeoIpException $e) {
    // Covers invalid IP, not-found, unknown attribute and remote failures.
    http_response_code(400);
    exit('ERROR: ' . $e->getMessage());
}

if ($format === 'json') {
    header('Content-Type: application/json; charset=utf-8');
    echo is_array($value) ? $formatter->toJson($value) : json_encode($value);
} else {
    header('Content-Type: text/plain; charset=utf-8');
    echo is_array($value) ? $formatter->toPlainText($value) : $value;
}

Swap new GeoIpLocator() for any provider to serve from a local database.

Requirements

• PHP 7.2 or newer
• Extensions: json, mbstring
• For the default remote provider: outbound HTTPS and either allow_url_fopen or ext-curl. No database needed.
• For local providers: a geolocation database from any supported provider
• For the IP2Location provider only: the ip2location/ip2location-php package (composer require ip2location/ip2location-php, needs ext-bcmath). The provider throws a clear MissingDependencyException if it's absent.

License & attribution

The code in this repository is released under the MIT License.

Database data is never bundled and carries its own license. You must obtain a database under that source's terms, and several require visible attribution wherever their data is shown. GeoIpLocator::attribution() returns the exact snippet for the active source.