A library that enables the usage of MaxmindDB geoIP databases by using the Rust library in a WebAssembly module
Uses the Rust MaxmindDB library to create a WASM binary that lets you query MaxMind databases directly in JavaScript/TypeScript.
- Node.js
- Deno
- Bun
- Browser
- Cloudflare Workers
npm install maxminddb-wasm
# or
pnpm add maxminddb-wasmDeno (jsr)
import { Maxmind } from "jsr:@josh-hemphill/maxminddb-wasm";import { readFile } from 'node:fs/promises';
import { Maxmind } from 'maxminddb-wasm/node-module';
const dbFile = await readFile('./GeoLite2-City.mmdb');
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');
console.log(result);
// ASN / ISP database (separate .mmdb file from MaxMind)
const asnDb = await readFile('./GeoLite2-ASN.mmdb');
const asnReader = new Maxmind(asnDb);
console.log(asnReader.lookup_isp('8.8.8.8'));
// Country database
const countryDb = await readFile('./GeoLite2-Country.mmdb');
console.log(new Maxmind(countryDb).lookup_country('8.8.8.8'));import { Maxmind } from "jsr:@josh-hemphill/maxminddb-wasm";
const dbFile = await Deno.readFile('./GeoLite2-City.mmdb');
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');
console.log(result);
const asnDb = await Deno.readFile('./GeoLite2-ASN.mmdb');
console.log(new Maxmind(asnDb).lookup_isp('8.8.8.8'));import init, { Maxmind } from 'maxminddb-wasm/browser';
await init();
const response = await fetch('/GeoLite2-City.mmdb');
const dbFile = new Uint8Array(await response.arrayBuffer());
const maxmind = new Maxmind(dbFile);
const result = maxmind.lookup_city('8.8.8.8');import init, { Maxmind } from 'maxminddb-wasm/browser';
import wasmModule from 'maxminddb-wasm/browser/index_bg.wasm';
export default {
async fetch(request, env) {
await init({ module_or_path: wasmModule });
const maxmind = new Maxmind(new Uint8Array(env.MAXMIND_DB));
const ip = request.headers.get('cf-connecting-ip');
const result = maxmind.lookup_city(ip);
return new Response(JSON.stringify(result));
}
};import { Maxmind } from 'maxminddb-wasm/node-module';
const dbFile = await Bun.file('./GeoLite2-City.mmdb').arrayBuffer();
const maxmind = new Maxmind(new Uint8Array(dbFile));
const result = maxmind.lookup_city('8.8.8.8');new Maxmind(dbFile: Uint8Array)Creates a new Maxmind instance with the provided database file.
Looks up city information for the given IP address. Also works with GeoLite2-Country databases for the overlapping country/continent fields; prefer lookup_country when you only need country data.
Looks up country/continent information for the given IP address. Intended for GeoLite2-Country / GeoIP2-Country databases (also works with City databases).
Looks up network prefix information for the given IP address.
Looks up ISP and ASN fields for the given IP address. The loaded database must be a compatible product (for example GeoLite2-ASN or GeoIP2-ISP). City databases do not contain these records.
Same as lookup_isp, plus the network prefix length for the matched entry (mirrors lookup_prefix for city data).
Read-only property that returns database metadata.
interface CityResponse {
city?: CityRecord;
continent?: ContinentRecord;
country?: CountryRecord;
subdivisions?: SubdivisionRecord[];
location?: LocationRecord;
}interface CityRecord {
geoname_id?: number;
names?: Record<string, string>;
}interface ContinentRecord {
code?: string;
geoname_id?: number;
names?: Record<string, string>;
}interface CountryRecord {
geoname_id?: number;
iso_code?: string;
names?: Record<string, string>;
}interface CountryResponse {
continent?: ContinentRecord;
country?: CountryRecord;
}interface SubdivisionRecord {
geoname_id?: number;
iso_code?: string;
names?: Record<string, string>;
}interface LocationRecord {
latitude?: number;
longitude?: number;
time_zone?: string;
}interface PrefixResponse {
city: CityResponse;
prefix_length: number;
}interface IspResponse {
asn?: AsnResponse;
isp?: string;
organization?: string;
mobile_country_code?: string;
mobile_network_code?: string;
}interface AsnResponse {
as_num?: number;
as_organization?: string;
}interface IspPrefixResponse {
isp: IspResponse;
prefix_length: number;
}interface Metadata {
binary_format_major_version: number;
binary_format_minor_version: number;
build_epoch: number;
database_type: string;
description: Record<string, string>;
ip_version: number;
languages: string[];
node_count: number;
record_size: number;
}For running the automated build (which includes compiling the rust wasm) you'll need the following tools installed:
Once you have all the necessary tools installed, you can just run pnpm build
Under tests/*, there are tests for each platform that can be run with the pnpm test command. On first run, it downloads the City, Country, and ASN MaxMind test databases.