@gautric/node-red-ipinfo

A Node-RED node that retrieves geolocation, network, and organization data for any IP address using the IPInfo.io API. Powered by the official node-ipinfo client library (v4.3.0).

Features

• IPv4 & IPv6 lookups with input validation
• Configurable caching (LRU) to reduce API calls and improve latency
• Customizable input/output message properties
• Internationalized status and error messages (i18n)
• Includes example flow importable from the Node-RED editor
• Built on node-ipinfo 4.3.0 — the latest official IPInfo.io Node.js client

Prerequisites

| Requirement | Version | |-------------|---------| | Node.js | ≥ 18 | | Node-RED | ≥ 4.0.8 | | node-ipinfo | ≥ 4.3.0 (installed automatically) | | IPInfo.io account | Free tier available at ipinfo.io/signup |

Installation

Node-RED Palette Manager

1. Open Node-RED → Menu → Manage palette
2. Search for @gautric/node-red-ipinfo
3. Click Install

Command Line

cd ~/.node-red
npm install @gautric/node-red-ipinfo

Quick Start

1. Drag an ipinfo node onto your flow.
2. Double-click it and create a new IPInfo Config node.
3. Paste your API token into the config.
4. Wire an inject node (payload = 8.8.8.8) → ipinfo → debug.
5. Deploy and click inject.

Node Reference

ipinfo

Looks up geolocation data for the IP address found in the incoming message.

| Property | Default | Description | |----------|-----------|-------------| | Input | msg.payload | Message property containing the IP address (string) | | Output | msg.payload | Message property where the result object is stored | | Config | — | IPInfo Config node to use |

Accepted input values

• Valid IPv4 address, e.g. 8.8.8.8
• Valid IPv6 address, e.g. 2001:4860:4860::8888
• The string me (returns info for the calling machine's public IP)

Output object

{
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "city": "Mountain View",
  "region": "California",
  "country": "US",
  "loc": "37.4056,-122.0775",
  "org": "AS15169 Google LLC",
  "postal": "94043",
  "timezone": "America/Los_Angeles"
  // additional fields depend on your IPInfo.io plan
}

Status indicators

| Color / Shape | Meaning | |---------------|---------| | 🔵 dot | Lookup in progress | | 🟡 ring | Invalid IP address (skipped) | | 🔴 ring | Configuration or input error | | 🔴 dot | API / network error | | (none) | Last lookup succeeded |

ipinfo-config

Shared configuration node holding your API credentials and cache settings.

| Property | Default | Description | |--------------|---------------|-------------| | Name | IPInfo Config | Display name | | Token | — | Your IPInfo.io API token (stored as credential) | | Timeout | 1000 ms | HTTP request timeout | | Cache | false | Enable LRU caching | | Max Items | 5000 | Maximum cached entries | | TTL | 86400000 ms (24 h) | Time-to-live per cache entry |

Example Flow

An example flow is bundled with the node. Import it from:

Menu → Import → Examples → @gautric/node-red-ipinfo

API Rate Limits

| Plan | Requests / month | |----------|-----------------| | Free | 50,000 | | Basic | 250,000 | | Standard | 500,000 | | Business | Custom |

Enable caching in the config node to stay within limits.

Troubleshooting

| Symptom | Likely cause | Fix | |---------|-------------|-----| | Red "Missing configuration" status | Config node not linked | Double-click the ipinfo node and select a config | | Red "Error" status after deploy | Invalid or missing API token | Check your token at ipinfo.io/account/token | | Yellow "Invalid IP" status | Input is not a valid IP string | Ensure msg.payload contains a valid IPv4/IPv6 address | | Timeout errors | Slow network or low timeout | Increase the timeout value in the config node | | Rate limit errors (HTTP 429) | Too many requests | Enable caching or upgrade your IPInfo.io plan |

Dependencies

| Package | Version | Purpose | |---------|---------|---------| | node-ipinfo | ^4.3.0 | Official IPInfo.io Node.js client |

Development

# Clone the repo
git clone https://github.com/gautric/node-red-ipinfo.git
cd node-red-ipinfo

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Add or update tests for your changes
4. Submit a pull request

Open an issue for bugs or feature requests.

Changelog

1.1.0

• Updated node-ipinfo dependency from 4.0.1 to 4.3.0
• Improved IPv6 validation (supports compressed and mixed notation)
• Added input validation for empty strings and missing token warnings
• Added nodeDone guard checks for backward compatibility with older Node-RED
• Added files field to package.json for leaner npm package
• Raised minimum Node.js version to ≥ 18 (12.x is EOL)
• Added unit tests
• Improved README with troubleshooting guide, API reference, and dependency docs
• Added i18n keys for all config labels

1.0.0

• Initial release

License

Apache-2.0

Support

If this project helps you, consider buying the developer a coffee. ☕