Local GeoIP database compiler

GeoForge

Build a reproducible GeoIP MMDB from multiple lite, public, and operator-published sources instead of trusting a single feed.

View on GitHub Accuracy model
Go MMDB Offline build Quality report
GeoForge consensus GeoIP data pipeline

GeoIP data is noisy. GeoForge makes the build process measurable.

Free and lite GeoIP databases are useful, but each source has blind spots: stale allocations, missing cities, inconsistent romanization, weak postal coverage, registry country mismatches, and coordinates that imply more precision than IP geolocation can support. GeoForge turns those independent feeds into a controlled local database with consensus scoring, normalization, and a quality gate after every build.

Consensus over one-source trust

GeoForge compares candidate records from DB-IP, GeoLite2, IP2Location, Sypex, and geofeeds. City names, state names, postal codes, and coordinates are scored together so agreement is stronger than any individual provider priority.

Better operational coverage

GeoNames postal and city data can fill missing postal codes, recover city names from postal codes, and attach stable city geoname IDs. RIR delegated stats keep registry country separate from the final geolocation country.

Local, repeatable, auditable

The downloader tracks checksums, ETags, and Last-Modified headers. If sources did not change, the existing MMDB is kept. Every build writes a CSV audit copy and a quality report for regression review.

Accuracy positioning

Designed to outperform a single lite source, not to overclaim premium-grade certainty.

GeoForge is strongest when multiple independent inputs agree on the same country, city, state, postal code, or nearby coordinate cluster. In those cases the output can be more stable than using DB-IP Lite, GeoLite2, IP2Location LITE, or Sypex alone. It also improves display quality by cleaning common administrative suffixes, city duplicates, parenthetical labels, and mojibake text artifacts.

Premium commercial databases can still be better for contractual SLA, mobile-carrier attribution, frequently updated enterprise networks, fraud-focused signals, and redistribution rights. GeoForge is best suited for teams that want a transparent local build process, stronger lite-source coverage, and control over the source mix.

CountryUsually matches or exceeds lite feeds through consensus and registry separation.
CityImproves when two or more independent sources agree or a trusted geofeed covers the prefix.
PostalUseful enrichment when supported by GeoNames and consistent city evidence.
PrecisionExposes `accuracy_radius_km` instead of implying exact physical location.

Source pipeline

DB-IP seed ranges
MaxMind GeoLite2
IP2Location LITE
Sypex Geo
Operator geofeeds
RIR delegated stats
GeoNames enrichment
MMDB + CSV audit

Use cases

Where GeoForge fits

  • Internal analytics dashboards that need local GeoIP lookup without a network call.
  • Traffic reporting where country and city stability matter more than address-level precision.
  • Edge or offline environments that need an MMDB file built from controlled inputs.
  • Data engineering teams that want to compare monthly source changes before promoting a new database.
  • Projects that use geofeeds to correct operator-owned ranges faster than vendor monthly updates.

Data quality controls

What is checked before release

  • Record count and prefix additions/removals.
  • Country, city, postal, and GeoNames ID coverage.
  • Average confidence and low-confidence share.
  • Country/city/postal regressions versus the previous build.
  • Text artifact detection after cleanup.
  • MMDB smoke lookups against sample IPs.

Output schema

Operational JSON shape

The MMDB stores a compact record with matched prefix, confidence, location fields, and country metadata. Time zone is computed from final coordinates; DST is left to the consumer at request time.

{
  "ip": "1.208.10.20",
  "matched_prefix": "1.208.0.0/12",
  "confidence": 85,
  "source_updated_at": "2026-05-20T00:00:00Z",
  "location": {
    "continent_code": "AS",
    "continent_name": "Asia",
    "country_code": "KR",
    "country_name": "South Korea",
    "registry_country_code": "KR",
    "subdivision_name": "",
    "city_geoname_id": 1835848,
    "city_name": "Seoul",
    "postal_code": "04524",
    "latitude": 37.56631,
    "longitude": 126.9772,
    "time_zone": "Asia/Seoul",
    "accuracy_radius_km": 20
  },
  "country_metadata": {
    "KR": {
      "country_name": "South Korea",
      "calling_code": "82",
      "currency_code": "KRW",
      "is_eu_member": false
    }
  }
}

Geofeed-ready

Allowlisted RFC 8805 feeds can be imported as operator-published candidates. GeoForge supports four-column and five-column feed rows and limits narrow IPv4 entries by default.

No bundled vendor data

The repository ships code, not licensed databases. Users provide their own credentials and accept the terms of each data provider before building derived outputs.

Built for GitOps

Build locks, checksum-based updates, deterministic output paths, and quality reports make the database lifecycle easier to review in automation.

Repository topics

geoip, ip-geolocation, mmdb, maxmind, geolite2, ip2location, db-ip, sypexgeo, geonames, geofeed, rfc8805, rir, golang, data-quality, offline, consensus