# IP Geolocation & Network Lookup (`automation-lab/ip-geolocation-network-lookup`) Actor

Resolve public IPv4 and IPv6 addresses into normalized country, region, city, coordinates, timezone, ASN, ISP, organization, CIDR network, status, and provenance records.

- **URL**: https://apify.com/automation-lab/ip-geolocation-network-lookup.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Developer tools
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.71 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## IP Geolocation & Network Lookup

Resolve supplied public IPv4 and IPv6 addresses into normalized **IP geolocation** records with country, region, city, coordinates, timezone, ASN, ISP, organization, CIDR network, lookup status, and source provenance.

Use this Actor for recurring fraud-screening enrichment, traffic analytics, localization, incident triage, and routing datasets without managing an IP database or provider API key.

### What does IP Geolocation & Network Lookup do?

The Actor accepts up to 100 IPv4 and IPv6 values per run.

It validates and deduplicates the supplied values.

For each unique value it saves one typed dataset row containing:

- normalized IP address and protocol version;
- explicit lookup status and message;
- continent, country, region, city, and postal code;
- approximate latitude and longitude;
- IANA timezone, abbreviation, and UTC offset;
- ASN, ISP, organization, and associated domain;
- CIDR network and reported host range;
- Regional Internet Registry when available;
- exact source URLs and retrieval time.

Malformed and reserved values remain visible as status rows instead of disappearing.

### Who is it for?

**Fraud and trust teams** can append location and network ownership to IP events before applying their own risk rules.

**Analytics engineers** can enrich visitor, signup, transaction, or event tables with normalized geographic dimensions.

**Security analysts** can add ASN, ISP, organization, network, and RIR context to indicators during triage.

**Network operations teams** can group addresses by autonomous system and CIDR allocation for routing analysis.

**Data engineers** can turn a mixed IPv4/IPv6 list into JSON, CSV, Excel, XML, or API output.

### Why use this IP geolocation lookup?

- One stable output row per unique supplied value
- Native IPv4 and IPv6 validation
- Location and network-owner fields in one dataset
- CIDR network enrichment rather than only an organization label
- Explicit invalid, reserved, quota, not-found, and upstream statuses
- Source provenance on every row
- Anonymous HTTPS sources with no customer API key
- Conservative 256 MB memory profile
- Sequential quota-aware requests and bounded retries
- No browser, cookies, account, or proxy required

### What IP and network data can you extract?

| Field | Meaning |
| --- | --- |
| `input` | Value exactly as supplied |
| `ip` | Normalized address, or `null` for malformed input |
| `ipVersion` | `4`, `6`, or `null` |
| `lookupStatus` | Primary lookup outcome |
| `statusMessage` | Validation, quota, or upstream detail |
| `continent` | Continent name |
| `continentCode` | Continent code |
| `country` | Country name |
| `countryCode` | ISO alpha-2 country code |
| `region` | Region or state name |
| `regionCode` | Provider region code |
| `city` | Associated city |
| `postalCode` | Approximate postal code |
| `latitude` | Approximate latitude |
| `longitude` | Approximate longitude |
| `timezone` | IANA timezone identifier |
| `timezoneAbbreviation` | Current timezone abbreviation |
| `timezoneUtcOffset` | Current UTC offset |
| `asn` | Autonomous system number |
| `isp` | Internet service provider |
| `organization` | Associated network organization |
| `domain` | Associated organization domain |
| `network` | CIDR allocation containing the IP |
| `networkStart` | Reported first host in the network |
| `networkEnd` | Reported last host in the network |
| `networkLookupStatus` | CIDR enrichment outcome |
| `rir` | Regional Internet Registry |
| `sourceName` | Primary geolocation source |
| `sourceUrl` | Exact geolocation endpoint |
| `networkSourceName` | CIDR source |
| `networkSourceUrl` | Exact CIDR endpoint |
| `retrievedAt` | ISO 8601 retrieval timestamp |

Unavailable fields are `null`.

### How to run an IP geolocation check

1. Open the Actor input page.
2. Add one or more public IPv4 or IPv6 addresses.
3. Set **Maximum lookup rows** when only the first unique values should be processed.
4. Click **Start**.
5. Open the Dataset tab when the run finishes.
6. Review `lookupStatus` and `networkLookupStatus` before downstream use.
7. Export JSON, CSV, Excel, XML, or RSS, or read the dataset through the API.

A useful first input is:

```json
{
  "ipAddresses": [
    "8.8.8.8",
    "1.1.1.1",
    "2606:4700:4700::1111"
  ],
  "maxItems": 3
}
```

### Input parameters

#### `ipAddresses`

Required array containing one to 100 strings.

Each value must be an IPv4 or IPv6 address.

Hostnames, URLs, CIDR blocks, ports, and arbitrary text are not resolved.

Duplicate normalized addresses are processed once.

Malformed input produces `lookupStatus: invalid_ip`.

Private, loopback, documentation, and other non-public ranges identified by the provider produce `lookupStatus: reserved`.

#### `maxItems`

Optional maximum number of unique supplied values to process.

The default and maximum are 100.

Invalid and reserved values count toward the limit because they produce useful status rows.

The hard limit keeps each run to at most 10% of the primary anonymous provider's documented 1,000-request daily quota per client IP.

### Output example

A successful IPv4 result has this shape:

```json
{
  "input": "8.8.8.8",
  "ip": "8.8.8.8",
  "ipVersion": 4,
  "lookupStatus": "found",
  "statusMessage": null,
  "continent": "North America",
  "continentCode": "NA",
  "country": "United States",
  "countryCode": "US",
  "region": "California",
  "regionCode": "CA",
  "city": "San Jose",
  "postalCode": "95113",
  "latitude": 37.3361663,
  "longitude": -121.8905913,
  "timezone": "America/Los_Angeles",
  "timezoneAbbreviation": "PDT",
  "timezoneUtcOffset": "-07:00",
  "asn": 15169,
  "isp": "Google LLC",
  "organization": "Google LLC",
  "domain": "google.com",
  "network": "8.8.8.0/24",
  "networkStart": "8.8.8.1",
  "networkEnd": "8.8.8.254",
  "networkLookupStatus": "found",
  "rir": "ARIN",
  "sourceName": "IPWho public IP geolocation API",
  "sourceUrl": "https://ipwho.is/8.8.8.8",
  "networkSourceName": "IP.guide public network API",
  "networkSourceUrl": "https://ip.guide/8.8.8.8",
  "retrievedAt": "2026-08-23T14:15:00.000Z"
}
```

IP-derived locations are approximate and may change as providers update their databases.

### Lookup statuses and failure behavior

`found` means the primary source returned a usable public-IP record.

`invalid_ip` means the supplied value was not valid IPv4 or IPv6 syntax.

`reserved` means the source identified a private, loopback, documentation, or other reserved range.

`not_found` means the source accepted the address shape but had no usable record.

`quota_exceeded` means the anonymous provider returned a quota response.

`upstream_error` means the primary source remained unavailable after bounded retries.

`networkLookupStatus: upstream_error` can appear on a successful geolocation row when only CIDR enrichment was unavailable.

Only rows with `lookupStatus: found` incur the per-item event.

### How much does it cost to resolve IP geolocation and network records?

Pay-per-event billing has two parts:

- `$0.0015` once when a run starts;
- one `item` event for each successfully resolved public IP.

The current BRONZE item price is `$0.00118` per successful IP lookup, with lower prices at higher usage tiers.

At BRONZE, one successful lookup costs about `$0.00268` including one start event.

At BRONZE, 10 successful lookups cost about `$0.0133` including one start event.

At BRONZE, 100 successful lookups cost about `$0.1195` including one start event.

Invalid, reserved, not-found, quota-exceeded, and upstream-error rows have no separate item event.

Apify Console shows the authoritative live estimate before a run.

### Fraud-screening enrichment workflow

Export public IP addresses associated with signups, sessions, transactions, or authentication events.

Run this Actor on a bounded batch.

Join output back to your source table using normalized `ip`.

Separate rows that do not have `lookupStatus: found`.

Use country, ASN, ISP, organization, and CIDR as signals in your own reviewed decision model.

The Actor does not produce a fraud score, identify a person, or decide whether an event is malicious.

### Traffic analytics enrichment

Resolve unique public IPs before joining results to event data.

Group downstream metrics by country, region, city, timezone, ASN, ISP, or network.

Keep `retrievedAt` and source fields with the enrichment record so historical snapshots remain auditable.

Do not treat an IP-derived city or coordinate as a precise device or household location.

### Network and security analysis

Use `asn`, `organization`, `network`, and `rir` to add routing context to indicators.

Compare IPv4 and IPv6 ownership for the same operator.

Group addresses by CIDR downstream.

Confirm high-impact operational or security decisions with authoritative RIR, routing, and internal telemetry sources.

This Actor is an enrichment utility, not a vulnerability scanner, VPN detector, or threat-intelligence verdict service.

### Scheduled runs and change comparison

Save a bounded address list in an Apify Task.

Run it on a schedule appropriate for your workflow.

Store finished datasets in your warehouse.

Compare country, ASN, organization, network, or timezone downstream.

The Actor does not itself maintain cross-run state, detect changes, or send alerts.

### Integrations and exports

Send datasets to Google Sheets for review.

Export CSV or Excel for analyst workflows.

Use webhooks to trigger Make, Zapier, or n8n after successful runs.

Load JSON into a warehouse for recurring event enrichment.

Use the API when the input list originates in another application.

### Run with the Apify API

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~ip-geolocation-network-lookup/runs?token=YOUR_TOKEN&waitForFinish=120" \
  -H "Content-Type: application/json" \
  -d '{"ipAddresses":["8.8.8.8","2606:4700:4700::1111"],"maxItems":2}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client
  .actor('automation-lab/ip-geolocation-network-lookup')
  .call({
    ipAddresses: ['8.8.8.8', '2606:4700:4700::1111'],
    maxItems: 2,
  });

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor(
    "automation-lab/ip-geolocation-network-lookup"
).call(run_input={
    "ipAddresses": ["8.8.8.8", "2606:4700:4700::1111"],
    "maxItems": 2,
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/ip-geolocation-network-lookup"
```

#### Claude Desktop, Cursor, and VS Code setup

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/ip-geolocation-network-lookup"
    }
  }
}
```

Example prompts:

- "Look up 8.8.8.8 and return country, timezone, ASN, ISP, and CIDR network."
- "Enrich this IPv4 and IPv6 list, then separate invalid and reserved values."
- "Group these public IP addresses by organization, ASN, country, and network."

### Accuracy, privacy, and provenance

IP geolocation is an estimate derived from network registration, routing, and provider data.

It does not reveal a precise device, household, or person.

City, postal, coordinates, timezone, organization, and network assignments can be missing, stale, or reassigned.

The Actor records exact source endpoints and retrieval time on every row.

Use authoritative registries and internal evidence when accuracy is critical.

Avoid sending personal or confidential identifiers alongside the IP list.

### Quotas and operational limits

The primary anonymous provider documents 1,000 free requests per client IP per day.

The Actor accepts at most 100 unique values per run and waits at least 1.1 seconds between primary lookups.

Transient 429 and server responses receive at most two attempts.

When quota exhaustion is detected, remaining values become `quota_exceeded` status rows without further provider requests.

Apify cloud egress can be shared, so a provider quota may already be partly consumed before a run starts.

For larger or guaranteed-volume workflows, use a provider plan and implementation designed for that contract rather than attempting to bypass public limits.

### Legality and responsible use

The Actor calls anonymous public HTTPS data services for commercial-compatible enrichment.

Respect provider terms, quotas, Apify policies, privacy law, and the requirements that apply to your dataset.

Do not use approximate IP geolocation as the sole basis for denying access, credit, employment, housing, insurance, or another high-impact decision.

Do not attempt to identify a person from approximate output.

### Troubleshooting

#### Why is `lookupStatus` `invalid_ip`?

Supply a bare IPv4 or IPv6 address.

Remove protocols, ports, CIDR suffixes, hostnames, and surrounding labels.

#### Why is `lookupStatus` `reserved`?

Private, loopback, documentation, link-local, multicast, and other special-use ranges are not public geolocation targets.

Check that the upstream system exported the public peer or client address you intended to analyze.

#### Why is `network` null when geolocation succeeded?

Inspect `networkLookupStatus` and `statusMessage`.

The separate network source may have had no CIDR record or may have been temporarily unavailable.

#### Why did several rows show `quota_exceeded`?

The provider quota is shared by client egress and resets on the provider's schedule.

Retry after the documented reset period with a smaller bounded batch.

Do not repeatedly restart a run to evade the provider limit.

### FAQ

#### Does the Actor accept domain names?

No.

Resolve hostnames with a DNS workflow first, then submit the resulting public addresses.

#### Does it support IPv6?

Yes.

IPv6 syntax, geolocation, ASN ownership, and CIDR network lookup are supported when the sources have records.

#### Does it detect VPNs, proxies, Tor, or fraud?

No.

It returns location and network context that you can combine with separate reviewed signals.

#### Are invalid and failed values saved?

Yes.

Status rows preserve one-to-one enrichment evidence, but only successful public-IP rows incur the item event.

#### Can I process more than 100 IPs per run?

No.

The bound is intentional because the selected anonymous provider has a daily quota.

Split recurring work across days or use a separately contracted data source for higher guaranteed volume.

#### Does it monitor changes?

No.

Schedule runs and compare datasets downstream when you need history or change detection.

### Related Automation Lab actors

Use [DNS Lookup](https://apify.com/automation-lab/dns-lookup) to resolve hostnames into DNS records before submitting public IP addresses.

Use [WHOIS Lookup](https://apify.com/automation-lab/whois-lookup) for domain registration data rather than IP geolocation.

Use [MX Record Checker](https://apify.com/automation-lab/mx-record-checker) for mail-routing diagnostics.

These Actors cover different network workflows and do not replace IP geolocation or CIDR enrichment.

# Actor input Schema

## `ipAddresses` (type: `array`):

IPv4 and IPv6 addresses to resolve. Duplicate normalized values are processed once. Invalid and reserved values produce status rows. Maximum 100 values per run protects the anonymous provider quota.

## `maxItems` (type: `integer`):

Maximum number of unique supplied values to process, including invalid or reserved status rows.

## Actor input object example

```json
{
  "ipAddresses": [
    "8.8.8.8",
    "1.1.1.1",
    "2606:4700:4700::1111"
  ],
  "maxItems": 3
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing all lookup and validation status rows.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "ipAddresses": [
        "8.8.8.8",
        "1.1.1.1",
        "2606:4700:4700::1111"
    ],
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/ip-geolocation-network-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "ipAddresses": [
        "8.8.8.8",
        "1.1.1.1",
        "2606:4700:4700::1111",
    ],
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/ip-geolocation-network-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "ipAddresses": [
    "8.8.8.8",
    "1.1.1.1",
    "2606:4700:4700::1111"
  ],
  "maxItems": 3
}' |
apify call automation-lab/ip-geolocation-network-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/ip-geolocation-network-lookup"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WDzv8Sz9h0XOJR55g/builds/s6Oeqy2u1ODHBOBkh/openapi.json