# Bulk IP Geolocation & Risk Lookup (`datascraperes/bulk-ip-geolocation-risk-lookup`) Actor Bulk IP geolocation and risk lookup for IPv4/IPv6 addresses. Get country, city, ASN, ISP, timezone, VPN, proxy, Tor, datacenter, and risk score data. - **URL**: https://apify.com/datascraperes/bulk-ip-geolocation-risk-lookup.md - **Developed by:** [DataScraperES](https://apify.com/datascraperes) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $0.50 / 1,000 ip resolveds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## Bulk IP Geolocation & Risk Lookup Resolve IPv4 and IPv6 addresses in bulk and export structured IP intelligence data. The Actor returns geolocation, network, timezone, and risk signals for each successfully resolved IP address. Use it for fraud checks, traffic analysis, log enrichment, abuse review, geo-based routing, security workflows, and IP-based lead or user enrichment. ### What You Get For each resolved IP, the dataset includes: - Location: country, country code, city, state or region, ZIP/postal code, latitude, longitude, timezone, and local time. - Network: ASN, organization, and ISP. - Risk signals: VPN, proxy, Tor, mobile network, datacenter, and risk score. - Run status: success flag plus stable error codes and clear messages for uncharged failed inputs. No external API key is required. ### Pricing This Actor uses pay-per-event pricing. - Charged event: `ip-resolved` - Billing unit: one successfully resolved public IP address - Invalid, private, reserved, scoped, and failed upstream lookups are not charged as `ip-resolved` events. The final price is shown in the Apify Store pricing tab before you start a run. ### Input Provide a list of public IPv4 or IPv6 addresses. ```json { "ips": ["1.1.1.1", "8.8.8.8", "2001:4860:4860::8888"], "batchSize": 1000, "timeoutSecs": 30, "maxRetries": 4, "deduplicate": true, "continueOnError": true } ```` #### Input Fields | Field | Type | Default | Description | | --- | --- | --- | --- | | `ips` | array of strings | required | Public IPv4 or IPv6 addresses to resolve. | | `batchSize` | integer | `1000` | Target inputs per batch. Large request URLs are split automatically. Maximum: `10000`. | | `timeoutSecs` | integer | `30` | HTTP timeout for each request. | | `maxRetries` | integer | `4` | Retries for rate limits, temporary network errors, and server errors. | | `deduplicate` | boolean | `true` | Removes duplicate IPs before lookup. | | `continueOnError` | boolean | `true` | Keeps the run going after an IP-specific lookup failure. Infrastructure failures stop the run safely. | With `continueOnError` enabled, valid public IPs continue processing while invalid, private, reserved, and IPv6 scope-qualified values are returned as uncharged error rows. A run containing no queryable public IPs writes the error rows and finishes with an error status. ### Output Results are saved to the default Apify Dataset. Each item represents one IP address. #### Output Fields | Field | Description | | --- | --- | | `ip` | Resolved IP address. | | `ok` | `true` when the IP was resolved successfully. | | `asn` | Autonomous system number. | | `organization` | Network organization. | | `isp` | Internet service provider. | | `country`, `countryCode` | Country name and ISO country code. | | `city`, `state`, `zipcode` | City, region/state, and postal code. | | `latitude`, `longitude` | Geographic coordinates. | | `timezone`, `localtime` | Timezone and local time reported for the IP. | | `isMobile` | Whether the IP belongs to a mobile network. | | `isVpn` | Whether the IP is associated with VPN traffic. | | `isTor` | Whether the IP is associated with Tor. | | `isProxy` | Whether the IP is associated with proxy traffic. | | `isDatacenter` | Whether the IP belongs to a datacenter network. | | `riskScore` | Risk score returned by the provider. | | `errorCode` | Stable machine-readable reason for an uncharged failed input. | | `errorStatus`, `errorMessage` | Optional HTTP status and user-friendly error details. | Common error codes include `INVALID_IP`, `NON_PUBLIC_IP`, `UNSUPPORTED_SCOPE_ID`, `UPSTREAM_BAD_REQUEST`, `UPSTREAM_NOT_FOUND`, `MISSING_UPSTREAM_RESULT`, and `URL_TOO_LONG`. The default Key-value store also contains an `OUTPUT` summary with requested, normalized, queryable, processed, resolved, and failed-by-cause counts. It reports HTTP retries, rate limits, response-recovery attempts, safe URL splits, resumed run segments, completion state, and whether a spending limit or input-specific error stopped the run. ### Example Output ```json { "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-07-04T09:14:22", "isMobile": false, "isVpn": false, "isTor": false, "isProxy": false, "isDatacenter": true, "riskScore": 0, "errorCode": null, "errorStatus": null, "errorMessage": null } ``` ### Notes - Supports IPv4 and IPv6. - Supports large lists with configurable batches and automatic URL-length-safe splitting. - Uses retries and backoff for rate limits and temporary failures. - Retries only omitted IPs when an upstream bulk response is incomplete. - Never sends private, reserved, or IPv6 scope-qualified addresses to the upstream provider. - Stops gracefully when the run reaches the configured Apify pay-per-event charge limit. - Preserves progress across Apify migrations and run restarts. - Stops on a persistent provider-wide failure instead of generating thousands of individual retry requests. - Results can be exported from Apify as JSON, CSV, Excel, XML, or RSS. # Actor input Schema ## `ips` (type: `array`): Public IPv4 or IPv6 addresses to resolve. Invalid, private, reserved, and scoped addresses are returned as uncharged error rows. ## `batchSize` (type: `integer`): Target number of inputs per processing batch. Requests are automatically split further when required by safe URL-length limits. ## `timeoutSecs` (type: `integer`): HTTP timeout for each ipquery request. ## `maxRetries` (type: `integer`): Retries for rate limits, transient network errors, and 5xx responses. ## `deduplicate` (type: `boolean`): Remove duplicate IPs before querying ipquery. ## `continueOnError` (type: `boolean`): When enabled, failed lookups are written as uncharged error rows and the Actor continues. ## Actor input object example ```json { "ips": [ "1.1.1.1", "8.8.8.8", "2001:4860:4860::8888" ], "batchSize": 1000, "timeoutSecs": 30, "maxRetries": 4, "deduplicate": true, "continueOnError": true } ``` # Actor output Schema ## `results` (type: `string`): Default dataset containing one row per successful resolved IP plus optional uncharged error rows. ## `summary` (type: `string`): JSON summary with input classification, processed, resolved, failed-by-cause, retry, safe-split, resume, completion, and charge-limit metrics. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "ips": [ "1.1.1.1", "8.8.8.8" ] }; // Run the Actor and wait for it to finish const run = await client.actor("datascraperes/bulk-ip-geolocation-risk-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "ips": [ "1.1.1.1", "8.8.8.8", ] } # Run the Actor and wait for it to finish run = client.actor("datascraperes/bulk-ip-geolocation-risk-lookup").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "ips": [ "1.1.1.1", "8.8.8.8" ] }' | apify call datascraperes/bulk-ip-geolocation-risk-lookup --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=datascraperes/bulk-ip-geolocation-risk-lookup", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Bulk IP Geolocation & Risk Lookup", "description": "Bulk IP geolocation and risk lookup for IPv4/IPv6 addresses. Get country, city, ASN, ISP, timezone, VPN, proxy, Tor, datacenter, and risk score data.", "version": "0.2", "x-build-id": "abp8jWYKz8vs7JOW7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datascraperes~bulk-ip-geolocation-risk-lookup/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datascraperes-bulk-ip-geolocation-risk-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datascraperes~bulk-ip-geolocation-risk-lookup/runs": { "post": { "operationId": "runs-sync-datascraperes-bulk-ip-geolocation-risk-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datascraperes~bulk-ip-geolocation-risk-lookup/run-sync": { "post": { "operationId": "run-sync-datascraperes-bulk-ip-geolocation-risk-lookup", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "ips" ], "properties": { "ips": { "title": "IP addresses", "minItems": 1, "type": "array", "description": "Public IPv4 or IPv6 addresses to resolve. Invalid, private, reserved, and scoped addresses are returned as uncharged error rows.", "items": { "type": "string", "minLength": 2 } }, "batchSize": { "title": "Batch size", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Target number of inputs per processing batch. Requests are automatically split further when required by safe URL-length limits.", "default": 1000 }, "timeoutSecs": { "title": "Request timeout", "minimum": 1, "maximum": 300, "type": "integer", "description": "HTTP timeout for each ipquery request.", "default": 30 }, "maxRetries": { "title": "Max retries", "minimum": 0, "maximum": 10, "type": "integer", "description": "Retries for rate limits, transient network errors, and 5xx responses.", "default": 4 }, "deduplicate": { "title": "Deduplicate IPs", "type": "boolean", "description": "Remove duplicate IPs before querying ipquery.", "default": true }, "continueOnError": { "title": "Continue on errors", "type": "boolean", "description": "When enabled, failed lookups are written as uncharged error rows and the Actor continues.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```