# ip-location-db: seven years of daily IP geolocation builds, and the URLs you have to keep fixing

> Twelve converted databases, three formats, two rolling release tags and a June 2026 distribution change that broke long-lived download URLs. A look at what is solid and what is fragile.

**sapics/ip-location-db** — ip to location database by ASN, GeoFeed, Whois, iptoasn.com, db-ip lite, GeoLite2

- Repository: https://github.com/sapics/ip-location-db
- Stars: 2,250 · Forks: 209
- Language: JavaScript
- License: not declared
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/sapics-ip-location-db

## What the repository actually is

ip-location-db has provided IP to location data in CSV and MMDB formats since 2019. It is not a geolocation engine and it does not compute anything at request time. Every file in it is a converted, republished artifact from an upstream provider, and the repository's job is to normalise the shape of those artifacts so that a download URL is predictable.

The tree reflects that. There is no application code, no library, and no test suite to speak of. What there is, is a directory per database: `dbip-asn/`, `dbip-city/`, `dbip-country/`, `geolite2-asn/`, `geolite2-city/`, `geolite2-country/`, `iptoasn-asn/`, `iptoasn-country/`, `origin-asn/`, `server-country/`, `user-country/`, plus a `tools/` directory that holds the conversion scripts, which is where the JavaScript in the repository's language breakdown comes from. There is a `CHANGELOG.md` and no license file at the root, which is correct rather than an oversight, and is worth explaining further down.

Roughly 2,200 stars and 207 forks with only two open issues tells you how little attention this project needs once it is working. It runs on a schedule, the outputs are files, and consumers pull them.

## Three database families, twelve directories

The README splits everything into three kinds of database: country, city and ASN. Each kind has its own standard format, and each has several sources behind it.

Country data is the widest set. Five sources ship it: `user-country/` and `server-country/`, both from GeoFeed and both on a daily refresh; `geolite2-country/` from MaxMind on a twice-weekly refresh; `dbip-country/` from DB-IP on a monthly refresh; and `iptoasn-country/` from IPtoASN on a daily refresh. City data is narrower, with DB-IP Lite and GeoLite2 represented. ASN data covers autonomous system numbers from DB-IP, GeoLite2, IPtoASN and a separate `origin-asn/` directory.

The country schema is three columns, which is the whole appeal of this project:

```csv
ip_range_start, ip_range_end, country_code
```

City data is where the format gets heavy, adding region, city, postcode, coordinates and timezone to the range:

```csv
ip_range_start, ip_range_end, country_code, state1, state2, city, postcode, latitude, longitude, timezone
```

Range-based rather than one-row-per-address is what makes these files usable. A single row covers an entire allocated block, so the country file stays small enough to load into memory or a binary search tree without ceremony.

## File naming as the API

The most valuable part of the README is the format matrix, because it turns a question about which file to use into a decision about a suffix. For country data you have a choice of CSV or MMDB, IPv4 or IPv6, a combined file or separate ones, numeric-address files, and CIDR-list files. The city table offers CSV or MMDB with gzip and 7z variants, plus separate numeric forms for IPv4 and IPv6.

That means roughly nine flavours per country database, and the naming follows a readable rule rather than an arbitrary one. The pattern is database name, then a scope suffix, then a representation suffix, then the extension: something like `user-country-ipv4.csv`, `user-country-ipv4.mmdb`, `user-country.csv`, or `user-country-ipv4-num.csv` for numeric addresses and `user-country-ipv4-cidr.csv` for CIDR notation.

If you are deciding what to load, the choice is mostly about your lookup pattern. CSV is easy to parse anywhere and easy to inspect. MMDB is the MaxMind format, smaller and faster to query through a reader library. The num and cidr variants exist for import into databases that want a different shape, so if your engine stores numeric addresses as integers, you avoid converting at load time.

The city files arrive as `.csv.gz` and `.csv.7z` rather than bare CSV, which is a practical choice given the row counts, but it does mean your fetch step needs decompression in the pipeline.

## The June 2026 distribution change, and what it cost

There is a warning at the top of the README that deserves the attention it gets: as of June 18, 2026, the distribution method for GitHub Releases was revised, and the reader is told to update their URLs accordingly. A project whose entire purpose is to hand out stable URLs changing its URL scheme is not a contradiction, but it is an operational event.

The current scheme uses two tags that are never versioned. The first is `latest`, which holds the actual data files. The second is `checksum`, which holds SHA-256 files for those downloads. The checksum release explains the addressing rule: take a download URL, replace `/download/latest/` with `/download/checksum/`, and append `.sha256` to the filename.

That gives a verification loop with no extra tooling. Take the file URL for the CSV you want, transform it the documented way, and fetch the `.sha256` to check what you downloaded. It is worth building that step into whatever refreshes your local copy, because the alternative is trusting a file over HTTP from a tag that is rewritten continuously.

The subtle part is that both release bodies are rewritten in place as data refreshes. The checksum release shows a publication date well before the update timestamp printed inside its own body. A rolling tag means the tag page is a pointer to now, not a record of a moment, so any tooling that pins by release date rather than by file path will silently hold stale data.

## Why there is no license file

The repository has no license file at the root, and the README explains licensing per database instead. That is the correct design for an aggregation project, because the terms genuinely differ by source and the strictest one governs.

The GeoFeed-derived databases, which covers `user-country/` and `server-country/`, are published under PDDL 1.0. The IPtoASN-derived country and ASN databases are also PDDL. The DB-IP Lite files are CC BY 4.0, which carries an attribution requirement you should honour. And the MaxMind GeoLite2 files carry the GeoLite2 License, which is not an open data license in the usual sense: it is free to use with an account, it is redistributed here as CSV and MMDB, and it comes with its own conditions that differ from the other sources.

This is why the README states the license in every table row rather than once at the top. If your use is compliance reporting, content moderation, or anything that gets shown to end users, you need to check which of the four sources your chosen file came from. CC BY 4.0 in particular wants a visible credit, which is an easy obligation to satisfy and an easy one to forget.

There is also a practical consequence for the ASN files. GeoLite2 and DB-IP do not ship the same ASN data as IPtoASN or the origin database, so the four ASN directories can disagree about the same address range. That is not a bug in the conversion, it is a property of the sources.

## Refresh cadence and staleness

Every row in the matrix has an Updated column, and reading it is the fastest way to build a realistic expectation about data age. Daily applies to the GeoFeed user and server country files and to the IPtoASN country file. Twice weekly applies to GeoLite2 country data, reflecting MaxMind's own update schedule. Monthly applies to the DB-IP Lite files.

So the freshest thing in the repository is a day old and the stalest is a month old, and both are correct for their source. What matters is that you know which category you are loading. A country lookup used for analytics reporting tolerates a month of lag. A country lookup used to apply regional content rules should not.

The city and ASN tables are narrower, which also means slower-moving. There is no city file from IPtoASN or from GeoFeed, so if you need city-level data your realistic choices are MaxMind and DB-IP, with DB-IP refreshing monthly and the city files compressed on the way out.

Because the project refreshes on a timer and publishes files, there is no upgrade step in the usual sense. There is also no deprecation window, which is the trade: you get fresh data with zero maintenance, and you give up the ability to pin a known version. If reproducibility matters to you, copy the file into your own storage on fetch and record the SHA-256 you verified.

## How to consume it

There is no install step, which is why this project has no usage example in the conventional sense. Consumption is a download. If you want the daily-updated country file in CSV, the URL pattern is stable enough to hard-code:

```bash
wget https://github.com/sapics/ip-location-db/releases/download/latest/user-country-ipv4.csv
```

From there the practical work is loading a range table and doing a binary search, since rows are sorted by start address and each row gives you both bounds. For IPv4 the numeric file is often the right choice for a custom lookup path, and for IPv6 you need a data structure that handles 128-bit ranges rather than assuming 32-bit integers fit.

If you would rather not write the loader, use the MMDB files with an existing MaxMind reader. That is the argument for the dual format: the CSV is for humans, quick scripts and custom pipelines, and MMDB is for production lookups where query speed matters.

Two operational notes. First, decompress the city files before loading, and if you refresh on a schedule, extract to a temporary name and rename so a reader never sees a half-written file. Second, if your service depends on any of these files, mirror them. The upstream tag is mutable by design, the URL scheme has changed once already, and a two-minute fetch that fails silently in a cron job is the failure mode nobody debugs quickly.

## Conclusion

This repository solves a problem that is genuinely tedious: converting a dozen differently licensed, differently formatted geolocation sources into one predictable set of filenames. The format mapping is clear, the CSV schema is documented, and the refresh cadence is stated per source so you know exactly how stale your data is. The fragility sits in the distribution layer. Two rolling tags mean no immutable version to pin, the checksum release body is rewritten in place so its publication date no longer describes its contents, and the June 2026 URL revision proved that even a stable-looking path can move underneath you. Treat the latest tag as a stream, verify against the checksum release, and keep a local copy of anything your service depends on.

## FAQ

### Is there a free database for IP geolocation?

Yes. This repository republishes free IP geolocation data as CSV and MMDB files under stable download URLs, covering country, city and ASN lookups. Country files come from GeoFeed, MaxMind GeoLite2, DB-IP Lite and IPtoASN, refreshed daily to monthly depending on the source, and the CSV format is a simple three-column range table.

### What format are the ip-location-db CSV files?

Country files have three columns: ip_range_start, ip_range_end and country_code. City files add state, city, postcode, latitude, longitude and timezone to the same range layout. Because each row covers a whole allocated range rather than a single address, lookups are done with a binary search over sorted ranges.

### How often are these IP databases updated?

It depends on the source. The GeoFeed user-country and server-country files and the IPtoASN country file refresh daily. MaxMind GeoLite2 country data refreshes twice weekly, matching MaxMind's own schedule. DB-IP Lite files refresh monthly. Every row in the README matrix states its own update frequency.

### Which license applies to these IP location files?

It differs by database, which is why the README lists a license per table row. GeoFeed and IPtoASN derived files are PDDL 1.0, DB-IP Lite files are CC BY 4.0 with an attribution requirement, and MaxMind GeoLite2 files carry the GeoLite2 License. Check the row for the specific file you plan to use.

### How do I verify a downloaded file from ip-location-db?

There is a second release tagged checksum that holds a .sha256 file for every data file. Take the download URL for the file you fetched, replace /download/latest/ with /download/checksum/, append .sha256 to the filename, and compare the two hashes. Both release tags are rolling and their bodies are rewritten as data refreshes.

## Sources

- [Issues](https://github.com/sapics/ip-location-db/issues)
- [README](https://github.com/sapics/ip-location-db/blob/main/README.md)
- [Releases](https://github.com/sapics/ip-location-db/releases)
- [sapics/ip-location-db on GitHub](https://github.com/sapics/ip-location-db)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sapics-ip-location-db