Bulk IP Geolocation & Risk Lookup

Resolve IPv4 and IPv6 addresses in bulk and receive structured IP intelligence for location, network, timezone, and risk analysis. The Actor separates successful resolved IPs from invalid or unavailable inputs while keeping all results in a predictable Apify Dataset.

Run Bulk IP Geolocation & Risk Lookup on Apify.

What this Actor can do

• Resolve public IPv4 and IPv6 addresses in bulk.
• Return country, region, city, postal code, coordinates, timezone, and local time.
• Return ASN, organization, and ISP information when available.
• Return VPN, proxy, Tor, mobile, datacenter, and risk-score signals.
• Normalize IPv4 and IPv6 text before processing.
• Remove duplicate addresses when deduplication is enabled.
• Keep invalid, private, reserved, scoped, and failed inputs as uncharged error rows.
• Continue processing valid inputs after individual lookup errors.
• Retry temporary network, rate-limit, and server failures automatically.
• Recover incomplete upstream batches by retrying only missing IPs.
• Resume progress after an Apify migration or interrupted run.
• Store detailed processing and charge-limit counters in the OUTPUT summary.

No external API key is required for this Actor. It only sends queryable public IP addresses for geolocation and risk lookup; private, reserved, loopback, link-local, multicast, and IPv6 scope-qualified addresses are not sent upstream.

Common use cases

• Enrich security, fraud, and abuse-review datasets.
• Add location context to server, traffic, or application logs.
• Identify hosting, datacenter, proxy, VPN, or Tor traffic.
• Build geo-based routing, personalization, or analytics workflows.
• Enrich leads, users, transactions, or account activity with network context.
• Prioritize suspicious IPs by risk signals and geographic patterns.

How it works

For every value in ips, the Actor:

1. Parses comma-separated, line-separated, array, IPv4, and IPv6 input values.
2. Normalizes valid addresses and optionally removes duplicates.
3. Classifies invalid and non-public addresses without sending them upstream.
4. Groups queryable addresses into safe request batches.
5. Retries temporary failures and splits a batch when the upstream service cannot accept it as a whole.
6. Writes successful intelligence rows and uncharged error rows to the default Dataset.
7. Persists progress and updates the OUTPUT record as the run advances.

The Actor manages internal batch size, request timeout, and retry behavior in code so the public input stays focused on the data and output options users actually need.

Quick start

No coding is required:

1. Open the Actor's Input tab.
2. Add one or more public IPv4 or IPv6 addresses under IP addresses.
3. Choose whether duplicate addresses should be removed.
4. Choose whether the run should continue after individual lookup errors.
5. Click Start.
6. Open the Dataset tab to inspect resolved and error rows.
7. Open the default Key-Value Store and select OUTPUT for the run summary.

For a first test, use 1.1.1.1 and 8.8.8.8 with the default options.

Pricing

This Actor uses pay-per-event pricing:

Event	Billing unit	What is charged
ip-resolved	One successfully resolved public IP	A result row that contains valid geolocation and risk data and is delivered to the default Dataset

The current event price is shown by Apify in the Actor Store and before a run starts. Invalid IPs, non-public IPs, failed lookups, malformed responses, skipped work, and uncharged error rows are not charged as ip-resolved events.

Set a maximum charge in Apify before a large run to keep spending predictable. The Actor checks available pay-per-event capacity before starting new external work and stops safely when that capacity is exhausted.

Input

Field	Type	Required	Default	Description
ips	string[] or string	Yes	—	IPv4 or IPv6 addresses. Arrays, comma-separated values, and line-separated values are accepted.
deduplicate	boolean	No	true	Removes repeated normalized IP addresses before lookup.
continueOnError	boolean	No	true	Keeps processing after an IP-specific error and writes that error as an uncharged row.

The public input intentionally does not expose transport controls. Batch processing, request timeouts, and retries use stable internal defaults for consistent runs.

Input examples

Basic public IP lookup

{
  "ips": ["1.1.1.1", "8.8.8.8"]
}

IPv4 and IPv6 in one run

{
  "ips": [
    "1.1.1.1",
    "9.9.9.9",
    "2001:4860:4860::8888"
  ],
  "deduplicate": true,
  "continueOnError": true
}

Comma-separated and line-separated values

{
  "ips": "1.1.1.1, 8.8.8.8\n2001:4860:4860::8888"
}

Stop after the first input-specific error

{
  "ips": ["1.1.1.1", "not-an-ip", "8.8.8.8"],
  "continueOnError": false
}

Input normalization and classification

The Actor accepts standard IPv4 and IPv6 text. IPv6 addresses are normalized to their canonical representation before deduplication and lookup.

Input	Classification
1.1.1.1	Queryable public IPv4
2001:4860:4860::8888	Queryable public IPv6
192.168.1.1	Non-public and not sent upstream
fe80::1%eth0	Unsupported IPv6 scope identifier
not-an-ip	Invalid IP and not sent upstream

When deduplicate is enabled, repeated normalized values are processed once. Duplicate input counts remain visible in the OUTPUT summary.

Output

The default Dataset contains one row per processed input position. Successful rows contain geolocation, network, and risk data. Invalid or unsuccessful rows contain ok: false and a stable error code; those rows are not charged.

A typical successful item looks like this:

{
  "ip": "8.8.8.8",
  "ok": true,
  "asn": "AS15169",
  "organization": "Google LLC",
  "isp": "Google LLC",
  "country": "United States",
  "countryCode": "US",
  "city": "Mountain View",
  "state": "California",
  "zipcode": "94043",
  "latitude": 37.43903957944434,
  "longitude": -122.09837932325807,
  "timezone": "America/Los_Angeles",
  "localtime": "2026-08-19T09:14:22",
  "isMobile": false,
  "isVpn": false,
  "isTor": false,
  "isProxy": false,
  "isDatacenter": true,
  "riskScore": 0,
  "errorCode": null,
  "errorStatus": null,
  "errorMessage": null
}

Output fields

Field	Type	Meaning
ip	string	Normalized or original IP value associated with the row.
ok	boolean	true when intelligence data was resolved successfully.
asn	string or null	Autonomous system number.
organization	string or null	Network organization.
isp	string or null	Internet service provider.
country, countryCode	string or null	Country name and ISO country code.
city, state, zipcode	string or null	City, region/state, and postal code.
latitude, longitude	number or null	Geographic coordinates.
timezone, localtime	string or null	Timezone identifier and local time.
isMobile	boolean or null	Whether the address is associated with a mobile network.
isVpn	boolean or null	Whether the address is associated with VPN traffic.
isTor	boolean or null	Whether the address is associated with a Tor exit node.
isProxy	boolean or null	Whether the address is associated with a public proxy.
isDatacenter	boolean or null	Whether the address belongs to a datacenter network.
riskScore	integer or null	Risk score from 0 to 100 when available.
errorCode	string or null	Stable machine-readable reason for an unsuccessful row.
errorStatus	integer or null	Upstream HTTP status for an unsuccessful lookup, when available.
errorMessage	string or null	User-facing explanation of the unsuccessful lookup.

Error rows and status codes

Invalid, non-public, scoped, missing, and upstream-failed inputs remain in the default Dataset as uncharged rows with ok: false. Common error codes include:

• INVALID_IP: the value is not a valid IPv4 or IPv6 address;
• NON_PUBLIC_IP: the address is private, loopback, reserved, link-local, multicast, or otherwise non-public;
• UNSUPPORTED_SCOPE_ID: the IPv6 value contains a local scope suffix such as %eth0;
• UPSTREAM_BAD_REQUEST, UPSTREAM_NOT_FOUND, or UPSTREAM_UNPROCESSABLE: the upstream service rejected the request;
• MISSING_UPSTREAM_RESULT: the upstream response did not include a requested IP;
• URL_TOO_LONG: the value could not be safely encoded into a request;
• UPSTREAM_RATE_LIMIT, UPSTREAM_SERVER_ERROR, UPSTREAM_TIMEOUT, or UPSTREAM_NETWORK_ERROR: a temporary or provider-side failure;
• UPSTREAM_INVALID_RESPONSE: the response could not be interpreted as IP intelligence data.

Run summary and recovery

The Actor stores an OUTPUT record in the default Key-Value Store. It includes original, normalized, queryable, processed, resolved, and failed counts, plus invalid/non-public categories, request and retry counters, safe-batch recovery counters, charge-limit state, completion state, and run segments.

Example summary:

{
  "totalInputIps": 3,
  "normalizedInputIps": 3,
  "queryableInputIps": 3,
  "deduplicatedIps": 0,
  "processedIps": 3,
  "unprocessedIps": 0,
  "resolvedIps": 2,
  "failedIps": 1,
  "invalidIps": 1,
  "nonPublicIps": 0,
  "unsupportedScopedIps": 0,
  "httpRequests": 1,
  "httpRetries": 0,
  "fallbackSplits": 0,
  "missingResultRetries": 0,
  "chargedEventName": "ip-resolved",
  "stoppedByChargeLimit": false,
  "stoppedOnError": false,
  "completed": true
}

Progress is persisted while the run advances. After an Apify migration or restart, already processed entries are recognized and are not requested or charged again.

Reliability and expected behavior

The Actor protects the upstream service and the run budget with stable internal batches, bounded request timeouts, and automatic retries. Oversized request URLs are split into safe sub-batches. If a bulk response omits some addresses, only the missing subset is retried.

When continueOnError is enabled, input-specific errors are written to the Dataset and the next inputs continue. When it is disabled, the run stops at the first effective input-specific error and records that state in OUTPUT.

Provider-wide failures are surfaced as an infrastructure error rather than creating a large number of duplicate or unproductive retries.

Limits and important notes

• Both IPv4 and IPv6 are supported.
• Only public, queryable addresses are sent to the upstream service.
• Duplicate handling is controlled by deduplicate; the default is enabled.
• riskScore is returned as provided and may be null when unavailable.
• Location and risk signals can change between runs.
• A result row does not guarantee that every optional field is populated.
• The maximum charge can stop a run before all input entries are processed.
• Results can be exported from Apify as JSON, CSV, Excel, XML, RSS, and other supported formats.

Exporting and integrations

Open the run's Dataset tab to preview, filter, and export resolved and error rows. The OUTPUT record is available through the default Key-Value Store API for downstream monitoring.

For recurring fraud, security, or traffic analysis, save the input as an Apify Task and attach a Schedule. Keep the IP list and public output options consistent when comparing snapshots.

The Dataset API, webhooks, and Apify integrations can forward completed results to spreadsheets, automation tools, databases, or your own application.

Frequently asked questions

Do I need an API key?

No. The Actor does not require you to enter an external API key.

Are private or local IP addresses sent upstream?

No. Private, loopback, link-local, reserved, multicast, and scoped addresses are classified locally and are not sent for lookup.

Why is ok false for an input?

The value may be invalid, non-public, scoped, unavailable upstream, affected by a temporary provider failure, or skipped because of the run charge limit. Use errorCode and errorMessage for the reason.

Can I submit IPv4 and IPv6 together?

Yes. They can be mixed in the same ips input.

Can I submit a string instead of an array?

Yes. Comma-separated and line-separated strings are accepted in addition to arrays.

Can I schedule recurring lookups?

Yes. Save the input as an Apify Task and attach a Schedule.

Is IP geolocation legal?

You are responsible for ensuring that your use of IP intelligence complies with applicable laws, contracts, privacy requirements, and third-party rights.

Support

If a run does not behave as expected, open the Actor's Issues tab and include:

• the Apify run ID;
• the input used, without tokens or other secrets;
• the affected IP value;
• the errorCode and errorMessage when present;
• the OUTPUT summary and expected behavior.

This information makes the issue easier to reproduce and resolve.