README
geoip-web-api
A web API for IP-based geolocation. Both IPv4 and IPv6 are supported. Suitable for use as an amp-geo fallback when self-hosting the AMP framework.
GeoIP database and reader
Option 1: MaxMind
Setup MaxMind's GeoIP Update program to fetch and maintain a GeoIP database. Select a free or paid database in MaxMind DB file format. A sample cron job to let geoipupdate
check for database updates each day at midnight looks like:
0 0 * * * geoipupdate -f /path/to/GeoIP.conf
This module uses node-maxmind for the database reader. When the database is updated on the filesystem, the reader should automatically reload without needing to restart this module.
Option 2: IP2Location
Setup IP2Location's Download Client script to fetch and maintain a GeoIP database. Select a free or paid database in BIN file format.
Optionally, if you need subdivision support, also download the ISO 3166-2 Subdivision Code database in CSV file format.
This module uses ip2ldb-reader for the database reader. When the database is updated on the filesystem, the reader should automatically reload without needing to restart this module.
Installation
This module has been tested with Node.js 10, 12, 14, and 16. Feel free to try other versions, but additional support is not promised.
Local installation
npm install geoip-web-api
Global installation
npm install -g geoip-web-api
Options
All properties are optional, provided the defaults are suitable.
{
// {number} Log level (0:Off, 1:Error, 2:Warn, 3:Info, 4:Debug)
"logLevel": 3,
// {number} Port where HTTP server should listen
"port": 3000,
// {Object.<string, boolean>} Enabled output values (see HTTP response section)
"enabledOutputs": {
"country": true,
"subdivision": true,
"ip": false,
"ip_version": false,
"data": false
},
// {boolean} Pretty JSON output
"prettyOutput": false,
// {Object.<string, string|null>} Dictionary of HTTP response headers for GET requests
"getHeaders": {},
// {Array<string>} Array of GET paths to which HTTP server should respond
"getPaths": ['/', '/*'],
// {Object} Allowed cross-origin requests (CORS)
"cors": {
// {Array<string>} Array of allowed CORS origins (exact match)
"origins": null,
// {RegEx|string} RegEx test for allowed CORS origins
"originRegEx": null
},
// {Object.<string, string>} MaxMind database and reader options
"maxmind": {
// {string} Filesystem path to MaxMind database (in MMDB format)
"dbPath": "./GeoLite2-Country.mmdb"
},
// {Object.<string, string>} IP2Location database and reader options
"ip2location": {
// {string} Filesystem path to IP2Location database (in BIN format)
"dbPath": "",
// {string} Filesystem path to IP2Location ISO 3166-2 Subdivision Code database (in CSV format)
"subdivisionCsvPath": ""
}
}
Additional information
enabledOutputs
- If an output is enabled but is not supported by the database, it will not be output in the final response.getHeaders
- Headers can be removed from the response by setting their values tonull
. TheContent-Type
andContent-Length
headers are generated automatically and cannot be removed; it is possible to change theContent-Type
header to another valid MIME type, but it is not possible to alterContent-Length
. TheETag
header additionally supports special values"strong"
and"weak"
to specify strong or weak ETag generation, respectively (weak by default).getPaths
- See Express Route paths documentation for allowed route patterns. Notice that the default configuration matches requests to any path.cors.origins
andcors.originRegEx
- If the incoming request has anOrigin
HTTP header that satisfies one of these tests (is incors.origins
array or satisfiescors.originRegEx
RegEx test), then anAccess-Control-Allow-Origin
header will be appended to the response with value equal to theOrigin
header. Note that ifcors.originRegEx
is available as a string, theRegExp
object will be built withnew RegExp(cors.originRegEx, 'i')
.maxmind
andip2location
- Only one of these properties should be provided. If both have validdbPath
properties, then MaxMind takes precedence.
When running this module as a command line application, these options should be saved in a JSON configuration file whose path is passed to the application with argument --config
. When using this module in your own Node.js application, these options should be passed to the GeoIpWebApi
constructor. See Usage section below.
Example options
{
"logLevel": 1,
"port": 8080,
"enabledOutputs": {
"ip": true,
"data": true
},
"getHeaders": {
"cache-control": "private, max-age=3600",
"X-Content-Type-Options": "nosniff"
},
"getPaths": ["/geoip/?"],
"cors": {
"origins": ["http://example.com", "http://example.net"],
"originRegEx": "^https://[a-z0-9\\-]+\\.example\\.(com|net)