GeoIP: Lookups, Databases and Setup in nginx, Apache, CDNs and Firewalls

GeoIP turns an IP address into an approximate place: a country, usually a region and city, a time zone, and the network that owns the address. Every lookup reads a GeoIP database, either a file on your own server or a provider’s database behind an API or CDN. This page covers lookups, record fields, databases vs. APIs, and GeoIP setup in nginx, Apache, CDNs, firewalls and online stores.

The box shows your public IP address and where an edge GeoIP lookup places it. That is your IP’s GeoIP.

What is GeoIP?

GeoIP (geo IP location) works by address blocks. Providers assign each block to a place, using registry records, routing data, location feeds that network operators publish, network measurements and user corrections. A lookup finds the block that contains the address and returns its place: an estimate for the whole block, not for one device. The IP geolocation guide explains the data sources in detail.

GeoIP only works for public IP addresses. Private addresses such as 192.168.1.20 or 10.0.0.5 are reused in millions of home and office networks at once, so they have no location. See local vs. public IP addresses.

Typical uses are language and currency defaults, licensing and legal restrictions, country allowlists for admin logins, fraud signals (IP country vs. billing country), regional analytics, ad geo-targeting and log enrichment.

How to do a GeoIP lookup

• Your own IP: see the box above.
• Any IP address: enter an IPv4 or IPv6 address on Where am I.
• Many IPs: the batch IP lookup API takes up to 1,000 addresses per request.

GeoIP lookup from code (API)

Send the address in ip and your key in the apikey header. Leave out ip to get the location of the calling machine.

curl -H "apikey: $IPLOOKUPAPI_KEY" \
  "https://api.iplookupapi.com/v1/info?ip=80.110.0.1"

The response, trimmed:

{
  "data": {
    "ip": "80.110.0.1",
    "type": "v4",
    "connection": {
      "asn": 8412,
      "organization": "Magenta Telekom GmbH",
      "isp": "Magenta Telekom",
      "range": "80.110.0.0/24"
    },
    "location": {
      "continent": { "code": "EU", "name": "Europe" },
      "country": {
        "alpha2": "AT",
        "alpha3": "AUT",
        "name": "Austria",
        "is_in_european_union": true
      },
      "region": { "alpha2": "AT-9", "name": "Vienna" },
      "city": { "name": "Vienna" },
      "zip": "1010",
      "latitude": 48.198674,
      "longitude": 16.348388
    },
    "timezone": {
      "id": "Europe/Vienna",
      "code": "CEST",
      "gmt_offset": 7200,
      "is_daylight_saving": true
    }
  }
}

Add fields=location.country.alpha2,timezone.id to get only the values you need. If the country is all you need, see the IP to country API.

GeoIP lookup on the command line

With a downloaded MMDB file, mmdblookup (package mmdb-bin on Debian and Ubuntu) looks up one address:

mmdblookup --file /usr/share/GeoIP/country.mmdb --ip 80.110.0.1 country iso_code
# prints:  "AT" <utf8_string>

The path after the address (country iso_code) depends on the database’s structure; leave it out to print the whole record. In Python and other languages, an MMDB reader library does the same in code. The older geoiplookup command reads only the legacy DAT format.

GeoIP location: what a GeoIP record contains

Currency, calling code and EU membership follow from the country. For error rates and their causes, read how accurate IP geolocation is.

GeoIP database vs. GeoIP API

A GeoIP database is a file you query on your own servers. A GeoIP API queries the provider’s current database for you.

IP geolocation database formats: MMDB and CSV

• MMDB is a binary format: a search tree over the bits of the IP address plus a data section with the records. One file can cover IPv4 and IPv6. Readers map it into memory and look up addresses in-process, so web servers, firewalls and log pipelines use it.
• CSV is plain text: one row per network (CIDR or start and end address) with a country code, or with an ID that points into a separate locations file. It suits imports into SQL databases and firewalls.
• DAT is the legacy binary format of the first GeoIP libraries.

Where to download a GeoIP database

Several companies offer geo IP database downloads in MMDB and CSV, usually a free country or city edition plus paid editions with more precision and more frequent updates. Most require an account and a license key. Compare update frequency, IPv6 coverage, license terms (commercial use, redistribution, attribution) and fields, then automate the download, because address blocks keep changing owners and regions. The regional internet registries’ free daily statistics files are no substitute: their country code shows where the holder is based, not where the addresses are used.

GeoIP in nginx, Apache, CDNs, firewalls and online stores

nginx GeoIP

nginx reads MMDB files in two ways:

• Built-in ngx_http_geoip_module: reads MMDB since nginx 1.31.7 (mainline, October 2026); in the stable 1.30 branch it reads only legacy DAT files. It is not built by default (--with-http_geoip_module).
• Third-party ngx_http_geoip2_module: works with older versions too. On Debian and Ubuntu, the package libnginx-mod-http-geoip2 installs and enables it.

This example allows /admin/ only from two countries:

# http {} context, ngx_http_geoip2_module
geoip2 /usr/share/GeoIP/country.mmdb {
    auto_reload 24h;
    $geoip2_country_code default=XX country iso_code;
}

map $geoip2_country_code $admin_allowed {
    default 0;
    US      1;
    CA      1;
}

server {
    listen 80;
    server_name example.com;

    location /admin/ {
        if ($admin_allowed = 0) {
            return 403;
        }
        # ... your usual root or proxy_pass
    }
}

With the built-in module on 1.31.7 or later, write geoip_country /usr/share/GeoIP/country.mmdb; and use $geoip_country_code (see the nginx GeoIP module documentation). Behind a load balancer or CDN, nginx sees the proxy’s address: set geoip2_proxy (or geoip_proxy) to the trusted proxy ranges so the module reads X-Forwarded-For, as explained in finding the real client IP.

Apache GeoIP

Apache httpd has no GeoIP module of its own. A third-party MMDB module reads the file and copies fields such as the country code into environment variables that you name. Apache’s own Require expr then decides:

# GEO_COUNTRY is set by your MMDB module (see its documentation)
<Location "/admin">
    Require expr "reqenv('GEO_COUNTRY') in { 'US', 'CA' }"
</Location>

Cloudflare CF-IPCountry and other CDN headers

A CDN already runs a GeoIP lookup for each request and can pass the result to your server as a header.

See Cloudflare’s IP geolocation documentation. To block or allow countries at the edge instead, write a WAF custom rule on the field ip.src.country.

pfSense GeoIP blocking with pfBlockerNG

1. Go to System > Package Manager > Available Packages and install pfBlockerNG.
2. Open Firewall > pfBlockerNG > General, check Enable and click Save.
3. Open the IP tab. In the GeoIP configuration section, enter the account ID and license key from a free account with the database vendor, then click Save. pfBlockerNG then updates the database daily.
4. Open IP > GeoIP, edit a continent, select the countries and set Action to Deny Inbound. Click Save.
5. Go to Firewall > pfBlockerNG > Update, select Update and click Run.

OPNsense GeoIP aliases

1. Go to Firewall > Aliases, open the GeoIP settings tab, paste the download URL of your country database into URL and click Apply. On the Business Edition, leave URL empty.
2. On the Aliases tab, add an alias, set Type to GeoIP and select the countries or whole regions. Save and apply.
3. Under Firewall > Rules > WAN, add a rule with Action Block and the alias as Source.
4. If the alias is too large to load, raise Firewall Maximum Table Entries under Firewall > Settings > Advanced.

Commercial firewalls call this a Geo-IP filter or region blocking. Allowing the few countries you need is easier to maintain than blocking most of the world.

Magento 2 and Adobe Commerce: GeoIP store switcher

Magento Open Source and Adobe Commerce do not pick a store view by IP on their own. GeoIP store switcher extensions detect the country, then suggest or redirect to the matching store view. On Adobe Commerce on cloud infrastructure, the included CDN module has a GeoIP option under Stores > Configuration > Advanced > System > Full Page Cache that shows a store-switch dialog or redirects, based on a country-to-store mapping. Three rules:

• Give each store view its own URL, so caches and search engines see one version per URL.
• Prefer a dialog to a redirect. Google mainly crawls from US addresses, so IP redirects can hide store views from search.
• In the EU, redirect only with the customer’s consent (see below).

GeoIP blocking: what it can and cannot do

Geo IP blocking cuts noise from automated attacks and enforces country rules, but it is not access control on its own:

• VPNs, proxies and Tor let anyone appear in an allowed country. Add authentication and rate limits, and VPN and proxy detection where fraud matters.
• Wrong locations block real users: travelers, roaming phones (their traffic often exits through the home network), company VPNs and satellite internet.
• Stale data blocks the wrong ranges. Update with every release, and cover IPv4 and IPv6.

GeoIP vs. GPS

Browsers share a precise position (from GPS, Wi-Fi and cell data) only after the user agrees. GeoIP never touches the device.

Is GeoIP free?

Yes, with limits. Free GeoIP databases are usually less precise or updated less often than paid editions, and their licenses can require attribution or limit redistribution. Free GeoIP API tiers have monthly quotas: the iplookupapi Free plan includes 150 lookups per month at up to 10 per minute, with location, ISP and ASN, time zone and currency data. For more volume, compare the plans.