n8n-nodes-ip-location

n8n-nodes-ip-location is an n8n Community Node package that adds an IP Geolocation node. The node accepts a public IPv4 address, calls the free ip-api.com endpoint, and returns the complete raw API response for use in workflow enrichment, security review, routing, and analytics automations.

The package integrates with one external service, ip-api.com, and does not require credentials or runtime dependencies outside n8n.

Installation

Install the package from n8n's Community Nodes settings using the package name:

n8n-nodes-ip-location

For self-hosted n8n deployments, you can also install it where your n8n instance loads community nodes:

npm install n8n-nodes-ip-location

Restart n8n after installation if your deployment does not reload community nodes automatically.

n8n Usage

1. Add the IP Geolocation node to a workflow.
2. Set IP Address to a public IPv4 address, or use an expression such as {{ $json.ipAddress }}.
3. Execute the workflow.

The node outputs one item for each input item. On success, the output json is the raw response returned by ip-api.com.

Input Parameters

| Parameter | Internal Name | Type | Required | Description | | --- | --- | --- | --- | --- | | IP Address | ipAddress | string | Yes | Public IPv4 address to look up. IPv6, empty values, malformed IPv4 addresses, and private or reserved IP ranges are rejected before the API request. |

Examples:

8.8.8.8
{{ $json.ipAddress }}
{{ $json.body.clientIp }}

Output Example

Successful lookups return the complete raw API response:

{
	"status": "success",
	"country": "United States",
	"countryCode": "US",
	"region": "CA",
	"regionName": "California",
	"city": "Mountain View",
	"zip": "94043",
	"lat": 37.4223,
	"lon": -122.0848,
	"timezone": "America/Los_Angeles",
	"isp": "Google LLC",
	"org": "Google Public DNS",
	"as": "AS15169 Google LLC",
	"query": "8.8.8.8"
}

Exact values vary by IP address and by the data returned by ip-api.com.

Batch Processing

Batch processing uses n8n's normal item iteration. Connect any upstream node that outputs multiple items, and configure IP Address with an expression that resolves per item, for example {{ $json.ipAddress }}.

Example input items:

[
	{ "ipAddress": "8.8.8.8" },
	{ "ipAddress": "1.1.1.1" },
	{ "ipAddress": "208.67.222.222" }
]

The node processes items sequentially and returns one output item per input item with pairedItem preserved. For large batches, throttle or split upstream data so the workflow stays within the ip-api.com free-tier limit.

Error Handling

The node validates input before calling ip-api.com and reports structured errors for known failure cases.

| Code | Behavior | | --- | --- | | MISSING_REQUIRED_INPUT | The IP address parameter is empty, null, or undefined. | | INVALID_IP_FORMAT | The value is not a valid IPv4 address. | | PRIVATE_IP | The address is private, local, reserved, benchmark, documentation, multicast, or otherwise not publicly geolocatable. | | IPV6_NOT_SUPPORTED | IPv6 input was provided. Use IPv4. | | API_UNAVAILABLE | The API could not be reached or returned an unexpected response. | | RATE_LIMIT_EXCEEDED | The API rate limit was reached. A retryAfter value is included when available. | | TIMEOUT | The request exceeded the 10 second timeout. |

When Continue On Fail is disabled, n8n stops execution for the item and surfaces the node error. When Continue On Fail is enabled, the node returns an output item that includes the original input fields plus structured error fields such as error, code, details, and retryAfter.

Example continueOnFail error output:

{
	"ipAddress": "192.168.0.1",
	"error": "Private or reserved IP addresses cannot be geolocated",
	"code": "PRIVATE_IP"
}

Rate Limit Notes

The free ip-api.com endpoint allows 45 requests per minute and does not require an API key. The free endpoint uses HTTP, not HTTPS, so queried IP addresses are transmitted without TLS. For sensitive production workflows, consider whether a paid HTTPS-capable geolocation provider or ip-api.com pro plan is appropriate.

This node processes input items sequentially and detects rate-limit responses. It does not add an artificial delay between successful requests, so high-volume workflows should add batching, waiting, or throttling in n8n.

Development

Use Node.js v22 or newer. This repository includes .nvmrc for Node.js v22.

Install dependencies:

npm install

Build the node:

npm run build

Run lint:

npm run lint

Run tests:

npm test

Run the n8n community package scan:

npx @n8n/scan-community-package n8n-nodes-ip-location

Repository

https://github.com/ricardolrm/n8n-nodes-ip-location

License

MIT