Node.js

Get geolocation data in your Node.js application.

Prerequisites

• Node.js 18+
• A Hummingbird API key (get one free)

Installation

No SDK required. Use the built-in fetch API or any HTTP client.

Usage

Using fetch (Node.js 18+)

const response = await fetch(
  'https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8',
  {
    headers: {
      'X-API-Key': process.env.HUMMINGBIRD_API_KEY,
    },
  }
);

const { success, data } = await response.json();

if (success) {
  const { location, time, currency } = data;
  console.log(`Location: ${location.city_name}, ${location.country_name}`);
  console.log(`Timezone: ${time.zone} (${time.abbr})`);
  console.log(`Currency: ${currency.symbol} ${currency.code}`);
  // Location: Mountain View, United States
  // Timezone: America/Los_Angeles (PST)
  // Currency: $ USD
}

Look up visitor's IP

Omit the ip parameter to look up the caller's IP address:

const response = await fetch(
  'https://api.hummingbirdapi.com/v1/geo/lookup',
  {
    headers: {
      'X-API-Key': process.env.HUMMINGBIRD_API_KEY,
    },
  }
);

const { data } = await response.json();
console.log(`Your IP: ${data.ip}`);

Express.js example

import express from 'express';

const app = express();

app.get('/api/location', async (req, res) => {
  const clientIP = req.ip || req.headers['x-forwarded-for'];

  const response = await fetch(
    `https://api.hummingbirdapi.com/v1/geo/lookup?ip=${clientIP}`,
    {
      headers: {
        'X-API-Key': process.env.HUMMINGBIRD_API_KEY,
      },
    }
  );

  const geo = await response.json();
  res.json(geo);
});

app.listen(3000);

Error handling

const response = await fetch(
  'https://api.hummingbirdapi.com/v1/geo/lookup?ip=8.8.8.8',
  {
    headers: {
      'X-API-Key': process.env.HUMMINGBIRD_API_KEY,
    },
  }
);

const result = await response.json();

if (!result.success) {
  console.error(`Error ${result.error_code}: ${result.error_message}`);
  // Handle specific error codes
  if (result.error_code === 30001) {
    // Rate limit exceeded - wait and retry
  }
} else {
  console.log(result.data);
}

Response

All responses use the unified envelope format with fields in this order: success, data, error, error_code, error_message.

{
  "success": true,
  "data": {
    "ip": "8.8.8.8",
    "ip_type": "ipv4",

    "location": {
      "continent_code": "NA",
      "continent_name": "North America",
      "country_code": "US",
      "country_code_iso3": "USA",
      "country_name": "United States",
      "country_capital": "Washington",
      "country_tld": ".us",
      "country_calling_code": "+1",
      "country_flag_emoji": "🇺🇸",
      "country_languages": ["en", "es"],
      "country_area_km2": 9833520,
      "country_population": 331449281,
      "country_neighbors": ["CA", "MX"],
      "country_is_eu": false,
      "region_code": "CA",
      "region_name": "California",
      "city_name": "Mountain View",
      "postal_code": "94043",
      "latitude": 37.386,
      "longitude": -122.084,
      "weather_code": "USCA0746"
    },

    "time": {
      "zone": "America/Los_Angeles",
      "abbr": "PST",
      "utc_offset": "-08:00",
      "utc_offset_seconds": -28800,
      "current_time": "2026-01-26T10:30:00-08:00",
      "current_timestamp": 1737913800,
      "is_dst": false
    },

    "currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$"
    },

    "network": {
      "asn": 15169,
      "asn_organization": "Google LLC",
      "isp": "Google LLC",
      "organization": "Google LLC",
      "connection_type": "Corporate",
      "user_type": "hosting"
    }
  },
  "error": false,
  "error_code": null,
  "error_message": null
}

Next steps

• Authentication — Secure your API key
• Rate Limits — Understand request limits
• Error Handling — Handle errors gracefully
• IP Geolocation API Reference — Full endpoint documentation