GeoLite2-City: a twice-weekly MaxMind mirror on npm and jsDelivr

A repository with one file in it

The repository listing is short enough to take in at a glance: a .github/ directory, GeoLite2-City.mmdb.gz, the README, a package.json and a package-lock.json.

That single file is the point. This is not a library, a tool or a server. It is a mirror of MaxMind's free GeoLite2-City database, republished under a different distribution channel so that the data can be consumed without an account, a key or a download form.

The npm package is named geolite2-city, the version in the manifest is 1.0.108, and the npm badge and download badge in the README point at that package. The homepage is geo.wp-statistics.com, and the README carries a last updated line of 2026-10-16, which matches the last push to the repository on the same date.

The maintainers are named at the end of the README, VeronaLabs and the WP Statistics team, and the relationship to the original data is stated plainly in the attribution section, which says the database is provided by MaxMind and asks that appropriate attribution be included as required by the CC BY-SA 4.0 licence.

So the structure of the whole project is: MaxMind produces the data under its own terms, an automated workflow republishes the file, and jsDelivr serves it to whoever asks. The interesting engineering is in the middle step, and the interesting risk is in the terms.

The distribution path is npm first and the CDN second

The README gives the direct download URL, and the database information table repeats it:

https://cdn.jsdelivr.net/npm/geolite2-city/GeoLite2-City.mmdb.gz

The path says what is happening. The file lives in the npm package, and jsDelivr serves files out of npm packages, so the CDN is a front end onto a published tarball rather than a separate upload. The npm side of it is the same install you would run for any other package, and the table lists it as npm install geolite2-city.

The file is a MaxMind DB, the standard binary format for this kind of database, and it is served compressed, at around 68 megabytes. That size is the practical constraint on the whole approach, because a file that large is not something you want to fetch on every page view, which is why the update cadence below matters and why the direct download URL is a deploy step rather than a runtime call.

The update schedule is the second thing the table sets out. The database is updated automatically every Tuesday and Friday, and the schedule section gives the detail: every Tuesday and Friday at 06:00 UTC, via GitHub Actions, with the source being MaxMind's own GeoLite2 free geolocation data, and the distribution being published to npm and then served through the CDN.

So there is no API to call and no key to rotate. There is a URL, a file, and a refresh twice a week. That simplicity is the appeal and also the thing to be careful with, as the next sections show.

The client libraries are the standard MaxMind ones

The README's quick start shows the same lookup in four languages, and the libraries are the ordinary MaxMind readers, which is the part worth noting: nothing about the client code changes because the file came from a mirror.

In PHP it is the GeoIp2 Database Reader, opening the mmdb file and calling the city method with an address. In Python it is the geoip2.database module with a Reader and a city call. In Node it is the reader from the MaxMind geoip2 node package, opened asynchronously and queried with the same method.

import geoip2.database

reader = geoip2.database.Reader('./GeoLite2-City.mmdb')
response = reader.city('128.101.101.101')

print(response.country.name)  # 'United States'
print(response.city.name)     # 'Minneapolis'

And for WordPress sites, the README shows the WP Statistics plugin's own geolocation factory, which is a convenience path for people who are already running that plugin and want the same database behind it.

The features list says what a record gives you: country, city, coordinates, timezone, and more, at city-level accuracy.

For a user, the practical consequence is that switching between the official download and this mirror is a change of file URL, not a change of code. That is the strongest argument for the mirror, because the parts of an application that are hardest to change, the reader calls and the field names, are untouched. The same is true of the related resources the README lists, a country-level database and a DbIP city lite alternative, which are separate packages in the same family, so a project that needs a lighter file or a different data source can move without touching its code either.

The licence is stated two different ways

This is the section that needs a careful reader, and the inconsistency is visible in the repository itself.

The README says the database is free and open source under the CC BY-SA 4.0 licence, the licence badge in the header points at the Creative Commons BY-SA 4.0 deed, and the attribution section repeats that appropriate attribution should be included as required by that licence.

The package manifest says something different. Its license field reads CC-BY-NC-SA-4.0, which adds the non-commercial element that the share-alike version does not have. The repository listing also records the licence as unknown, and the primary language field is empty, since the repository contains a binary database and a manifest rather than source code.

So the same project describes itself as share-alike in its documentation and as non-commercial share-alike in its package metadata. Neither of those is the licence of the underlying data, which belongs to MaxMind and is published by MaxMind under its own terms, and the README points at MaxMind's GeoLite2 page as the source of the update.

The practical advice is not to treat the README's licence line as the answer. Read MaxMind's own terms for the GeoLite2 data, read the LICENSE and manifest in this repository, and if the two conflict, ask VeronaLabs and the WP Statistics team which one they intend, because the difference between a share-alike licence and a non-commercial share-alike licence decides whether a commercial product may use the file.

The attribution requirement is not in doubt, though. Credit MaxMind.

Twice a week is the update, and it cuts both ways

The update cadence is the feature that makes this mirror useful and the feature that makes it awkward.

On the useful side, a database refreshed on Tuesday and Friday is fresher than one you downloaded months ago and forgot about, and because the refresh is automatic you do not have to notice a MaxMind release to keep your data current. The version number in the manifest, 1.0.108, tracks those publications rather than a release of code, which is why the repository has no GitHub releases at all: the npm package is the release channel.

On the awkward side, the URL is stable and the content behind it is not. A deployment that downloads on first boot and then keeps the file will drift from one that re-fetches, and two instances of the same application can answer differently for the same address depending on when each started. If you cache the file, you have to decide how often to refresh it, and if you do not cache it, you are pulling 68 megabytes on a schedule that is not yours.

There is a subtler consequence for reproducibility. A geolocation result is a fact about a database version, so any support ticket that says a user was in one city needs to be matched with the database version that produced it. Pinning the npm version rather than tracking latest is what makes that possible, and the version number is there for exactly that purpose.

The README's own last updated line, dated 2026-10-16, is a reminder that the file at any moment reflects a recent MaxMind release, and the same README tells you the next refresh is a Tuesday or a Friday away.

What this is for, and what to use instead

The scope is narrow, and knowing where the edges are saves an afternoon.

It is city-level data. The features list says country, city, coordinates and timezone, and the related resources include a separate country-level database for people who need less, and a DbIP city lite alternative for people who want a different data source. The city database is the one you want when you are labelling a visitor by their town, and the wrong one if you are trying to resolve a street address.

It is also the wrong tool for anything that needs a guarantee. The README is explicit that the data is refreshed on a schedule, and IP geolocation data is a moving target in any case, with address ranges reassigned and mobile carriers routing traffic from surprising places. If your product needs to know where someone is with confidence, a database is the wrong mechanism, and if it needs to know where someone is roughly, this is a very cheap way to find out.

For the WordPress case specifically, the plugin route in the README is the shortest path, since the geolocation factory in the example uses the plugin's own service and therefore the same data underneath.

Two operational details are worth carrying into a deployment. The compressed file is large enough that you want it in a build step or a scheduled job rather than in a request path. And the file is a binary, so it belongs in a container image or an artefact store, and the update schedule becomes your problem only if you let it be your problem.

In the end this is a convenience layer over someone else's data, and it is worth using precisely because it is boring: one file, one URL, a documented schedule, and a client API that matches the official one.

Editorial conclusion

Adopt this mirror if you need city-level IP geolocation in a small application and want to avoid registering for a MaxMind account, since the file is fetched directly and refreshed twice a week. Do not adopt it as a substitute for reading MaxMind's own terms, because the data is MaxMind's and the repository states its licence in two conflicting ways, one of which is non-commercial. Before you ship it, check the attribution requirement, because the README asks you to credit MaxMind, and pin the version you tested with, since the same URL serves different data every Tuesday and Friday and a geolocation result that changes under you is a support problem you did not have before.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. wp-statistics/GeoLite2-City on GitHub