Getting Started with IP Geolocation Middleware in Express.js

Intro #

Express.js is a lightweight and flexible web application framework for Node.js. It makes it easier to build web servers, APIs, and backend services by providing a simple routing system, request handling, response helpers, and support for tools like IP geolocation middleware. Instead of manually handling every HTTP request using Node.js built-in modules, Express.js gives developers a cleaner and more organized way to define endpoints such as GET, POST, PUT, and DELETE.

Middleware is one of the most important concepts in Express.js. A middleware function sits between the incoming request and the final route handler. It can inspect, modify, or enrich the request before passing it to the next function in the request pipeline. Common middleware examples include request logging, authentication, JSON body parsing, error handling, and IP geolocation lookup. In this tutorial, we will integrate the IP2Location middleware to automatically include visitor location details right within the Express.js request object.

Basic Usage of the IP2Location Middleware in Express.js #

For this tutorial, we’ll be using a Debian 13 server to demonstrate the usage of the IP2Location middleware in Express.js. Therefore, the steps you’ll see are specifically for that operating system.

Step 1: Update the Debian Server #

First, update the package list and upgrade existing packages:

sudo apt update
sudo apt upgrade -y

Step 2: Install Node.js and npm #

Install Node.js and npm from the Debian repository:

sudo apt install -y nodejs npm

After installation, verify that Node.js and npm are available:

node -v
npm -v

You should see the installed versions printed in the terminal.

Step 3: Create a New Test Project #

Create a new project directory for the Express.js test application:

mkdir ip2location-express-demo
cd ip2location-express-demo

Initialize a new Node.js project:

npm init -y

This creates a package.json file, which stores the project metadata and dependencies.

Step 4: Install Express.js and IP2Location #

Install Express.js and the IP2Location Node.js module:

npm install express ip2location-nodejs

Step 5: Prepare the IP2Location BIN Database #

The IP2Location Node.js module works with an IP2Location BIN database file. You can use either the free LITE BIN files or the commercial BIN files for better accuracy.

Upon login to the user dashboard, navigate to the Download section and download your desired BIN file. You can use the database package that matches your project requirements, such as country-level, city-level, ISP-level, or full geolocation data.

After downloading the zipped file containing your BIN file, extract the BIN file and place your BIN file inside the project directory. In our case, we’ll be using the DB26 IPv6 BIN file.

Step 6: Create the Express.js Test Server #

Create a new file named server.js:

nano server.js

Add the following code:

const express = require("express");
const {IP2Location} = require("ip2location-nodejs");

const app = express();
const ip2location = new IP2Location();

ip2location.open("./IPV6-COUNTRY-REGION-CITY-LATITUDE-LONGITUDE-ZIPCODE-TIMEZONE-ISP-DOMAIN-NETSPEED-AREACODE-WEATHER-MOBILE-ELEVATION-USAGETYPE-ADDRESSTYPE-CATEGORY-DISTRICT-ASN.BIN ");

// Optional: enable this only if your app is running behind a trusted proxy
app.set("trust proxy", true);

// Use IP2Location middleware
app.use(ip2location.middleware());

app.get("/", (req, res) => {
  if (req.ip2location && req.ip2location.status === "OK") {
    res.json(req.ip2location);
  } else {
    console.error(req.ip2location?.status || "No IP2Location result");

    res.status(400).json({
      status: "ERROR",
      message: req.ip2location?.status || "Unable to retrieve IP2Location result",
    });
  }
});

// Error handler
app.use((err, req, res, next) => {
  console.error("Middleware error:", err);

  res.status(500).json({
    status: "ERROR",
    message: err.message,
  });
});

app.listen(3000, () => {
  console.log("Test server running at http://localhost:3000");
});

Save and close the file.

Step 7: Run the Express.js Server #

Start the test server:

node server.js

If everything is working correctly, you should see:

Step 8: Test the Middleware #

From the same server, you can test the endpoint with curl:

curl http://localhost:3000

The response should return the IP2Location lookup result in JSON format.

{"ip":"::1","ipNo":"1","countryShort":"-","countryLong":"-","region":"-","city":"-","isp":"Loopback","domain":"-","zipCode":"-","latitude":0,"longitude":0,"timeZone":"-","netSpeed":"-","iddCode":"-","areaCode":"-","weatherStationCode":"-","weatherStationName":"-","mcc":"-","mnc":"-","mobileBrand":"-","elevation":"0","usageType":"RSV","addressType":"U","category":"IAB24","district":"-","asn":"-","as":"-","asDomain":"-","asUsageType":"-","asCidr":"-","status":"OK"}

Note that there is no geolocation data there as the localhost is a private IP address.

Let’s try from a browser instead and see what we get.

In your browser, navigate to the URL below:

http://<YOUR SERVER IP>:3000

The IP2Location middleware will process the incoming request and attach the lookup result to req.ip2location. You should see something like this:

Notes About “trust proxy” #

The line below is useful when your Express.js application is running behind a reverse proxy, load balancer, or CDN:

app.set("trust proxy", true);

When enabled, Express.js may use the X-Forwarded-For header to determine the original client IP address. However, this should only be enabled when your application is behind a trusted proxy. In production, avoid blindly trusting all proxies unless you fully control the proxy layer.

Conclusion #

Hope you’ve found our simple guide to using the IP2Location middleware in Express.js useful for your own needs. You can easily adapt the codes above to meet your own requirements.