# Ip Geolocation Lookup - Bulk IP Location, ISP & ASN (`apizy/ip-geolocation-lookup`) Actor Resolve IP addresses in bulk with accurate geolocation data including country, region, city, coordinates, and timezone. Optionally enrich results with ISP, ASN, and organization data. Ideal for analytics, fraud review, and traffic enrichment. - **URL**: https://apify.com/apizy/ip-geolocation-lookup.md - **Developed by:** [Apizy](https://apify.com/apizy) (community) - **Categories:** Lead generation, SEO tools, Developer tools - **Stats:** 5 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 Lookup Lookup IP addresses in bulk to get **country, region, city, latitude, longitude, timezone**, and optional **network enrichment** such as ISP, ASN, and organization. Supports both **IPv4** and **IPv6**. No coding needed. Get results via Dataset, Key-value store `OUTPUT`, or API. ### Why Use IP Geolocation Lookup? - **Bulk lookup**: Process dozens to thousands of IP addresses in one run. - **IPv4 and IPv6 support**: Validate and resolve both major IP versions. - **Location data**: Get country, region, city, coordinates, and timezone. - **Optional network enrichment**: Add ISP, ASN, and organization only when needed. - **Apify platform**: Schedule runs, API access, monitoring, integrations. - **Export ready**: JSON/CSV download, perfect for analytics, fraud checks, and network enrichment workflows. ### Features - Bulk IP lookup. - IPv4 and IPv6 validation. - Country, region, city, latitude, longitude, and timezone lookup. - Optional ISP, ASN, and organization enrichment. - Invalid IP detection with consistent `null` fallback fields. - Structured output for pipelines, dashboards, and API automation. ### Understanding `includeNetwork` `includeNetwork` is a **boolean trigger** that controls whether the Actor also fetches **network enrichment** fields in addition to location data. #### When `includeNetwork` is `false` The Actor returns only: - `input` - `isValid` - `ipVersion` - `location` This is the best option when you only need geolocation and want faster, simpler output. #### When `includeNetwork` is `true` The Actor also adds: - `network.isp` - `network.organization` - `network.asn` This is useful when you want to know which provider or network owns the IP address. #### Why `includeNetwork` is optional Network enrichment is not always needed. Many use cases only care about geolocation such as country, city, and timezone. Making `includeNetwork` optional keeps the Actor lighter and avoids unnecessary processing when ISP/ASN data is not required. ### Input Options Click the [input tab](#input) for the full schema. | Field | Type | Description | Default | | ---------------- | ------- | ------------------------------------------------------ | ------- | | `ips` | Array | List of IPv4 or IPv6 addresses to lookup in bulk. | — | | `includeNetwork` | Boolean | Include ISP, ASN, and organization data in the output. | `false` | **Notes:** - `ips` is the only required field. - The Actor validates each item to determine whether it is a valid IPv4 or IPv6 address. - If an IP is invalid, `isValid` returns `false`, and `location` returns `null`. - If `includeNetwork` is disabled, the `network` field is not included in the output. - If `includeNetwork` is enabled but lookup fails, `network` returns `null`. *** #### Example: Geolocation only ```json { "ips": ["8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999"] } ``` **Output:** ```json [ { "input": "8.8.8.8", "isValid": true, "ipVersion": "IPv4", "location": { "country": "United States", "countryCode": "US", "region": "Virginia", "city": "Ashburn", "latitude": 39.03, "longitude": -77.5, "timezone": "America/New_York" } }, { "input": "1.1.1.1", "isValid": true, "ipVersion": "IPv4", "location": { "country": "Australia", "countryCode": "AU", "region": "Queensland", "city": "South Brisbane", "latitude": -27.4766, "longitude": 153.0166, "timezone": "Australia/Brisbane" } }, { "input": "2001:4860:4860::8888", "isValid": true, "ipVersion": "IPv6", "location": { "country": "Canada", "countryCode": "CA", "region": "Quebec", "city": "Montreal", "latitude": 45.5019, "longitude": -73.5674, "timezone": "America/Toronto" } }, { "input": "999.999.999.999", "isValid": false, "ipVersion": null, "location": null } ] ``` #### Example: Geolocation + network enrichment (includeNetwork: true) ```json { "ips": ["8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999"], "includeNetwork": true } ``` **Output:** ```json [ { "input": "8.8.8.8", "isValid": true, "ipVersion": "IPv4", "location": { "country": "United States", "countryCode": "US", "region": "Virginia", "city": "Ashburn", "latitude": 39.03, "longitude": -77.5, "timezone": "America/New_York" }, "network": { "isp": "Google LLC", "organization": "Google Public DNS", "asn": "AS15169 Google LLC" } }, { "input": "1.1.1.1", "isValid": true, "ipVersion": "IPv4", "location": { "country": "Australia", "countryCode": "AU", "region": "Queensland", "city": "South Brisbane", "latitude": -27.4766, "longitude": 153.0166, "timezone": "Australia/Brisbane" }, "network": { "isp": "Cloudflare, Inc", "organization": "APNIC and Cloudflare DNS Resolver project", "asn": "AS13335 Cloudflare, Inc." } }, { "input": "2001:4860:4860::8888", "isValid": true, "ipVersion": "IPv6", "location": { "country": "Canada", "countryCode": "CA", "region": "Quebec", "city": "Montreal", "latitude": 45.5019, "longitude": -73.5674, "timezone": "America/Toronto" }, "network": { "isp": "Google LLC", "organization": "Google LLC", "asn": "AS15169 Google LLC" } }, { "input": "999.999.999.999", "isValid": false, "ipVersion": null, "location": null, "network": null } ] ``` #### Example: Single IPv4 lookup ```json { "ips": ["8.8.8.8"] } ``` **Output:** ```json [ { "input": "8.8.8.8", "isValid": true, "ipVersion": "IPv4", "location": { "country": "United States", "countryCode": "US", "region": "Virginia", "city": "Ashburn", "latitude": 39.03, "longitude": -77.5, "timezone": "America/New_York" } } ] ``` #### Example: Single IPv6 lookup ```json { "ips": ["2001:4860:4860::8888"], "includeNetwork": true } ``` **Output:** ```json [ { "input": "2001:4860:4860::8888", "isValid": true, "ipVersion": "IPv6", "location": { "country": "Canada", "countryCode": "CA", "region": "Quebec", "city": "Montreal", "latitude": 45.5019, "longitude": -73.5674, "timezone": "America/Toronto" }, "network": { "isp": "Google LLC", "organization": "Google LLC", "asn": "AS15169 Google LLC" } } ] ``` #### Example: Invalid IP input ```json { "ips": ["999.999.999.999", "invalid-ip"], "includeNetwork": true } ``` **Output:** ```json [ { "input": "999.999.999.999", "isValid": false, "ipVersion": null, "location": null, "network": null }, { "input": "invalid-ip", "isValid": false, "ipVersion": null, "location": null, "network": null } ] ``` *** ### Output Data Results saved to **default Dataset** (export JSON/CSV) and **Key-value store `OUTPUT`**. #### Output Fields | Field | Type | Description | Example | | ---------------------- | ------------ | --------------------------------------------------------------------------- | ---------------------- | | `input` | String | Original IP address input | `"8.8.8.8"` | | `isValid` | Boolean | Whether the input is a valid and successfully resolved IP address | `true` | | `ipVersion` | String|null | Detected IP version: `IPv4`, `IPv6`, or `null` if invalid | `"IPv4"` | | `location.country` | String|null | Resolved country name | `"United States"` | | `location.countryCode` | String|null | ISO 2-letter country code | `"US"` | | `location.region` | String|null | Region or state name | `"Virginia"` | | `location.city` | String|null | Resolved city | `"Ashburn"` | | `location.latitude` | Number|null | Latitude coordinate | `39.03` | | `location.longitude` | Number|null | Longitude coordinate | `-77.5` | | `location.timezone` | String|null | IANA timezone name | `"America/New_York"` | | `network.isp` | String|null | Internet service provider. Present only if `includeNetwork: true` | `"Google LLC"` | | `network.organization` | String|null | Organization or network owner. Present only if `includeNetwork: true` | `"Google Public DNS"` | | `network.asn` | String|null | ASN / autonomous system information. Present only if `includeNetwork: true` | `"AS15169 Google LLC"` | #### IP Version Values | Value | Description | | ------ | ------------------------------ | | `IPv4` | Valid IPv4 address | | `IPv6` | Valid IPv6 address | | `null` | Invalid input or lookup failed | ### How to Use IP Geolocation Lookup 1. **Prepare your IPs** — collect IPv4 and/or IPv6 addresses. 2. **Add them to `ips`** — provide one or many addresses in an array. 3. **Enable `includeNetwork` if needed** — use this only when you also want ISP, ASN, and organization data. 4. **Run Actor** — results appear in Dataset and key-value store `OUTPUT`. 5. **Export** — download as JSON or CSV, or fetch via API. 6. **Schedule / API** — automate recurring IP enrichment workflows. > 💡 **Quick test:** Run now with `8.8.8.8` and `1.1.1.1` to validate your setup in seconds. ### Pricing - **Free trial**: ~$5 credits covers extensive testing. - **Pay-per-run**: Low compute usage for standard bulk lookups. - Scales well for analytics, enrichment, and validation workflows. ### Tips - **Use bulk input** to process multiple IPs in a single run efficiently. - **Enable `includeNetwork` only when needed** to keep output lighter and easier to consume. - **Use `ipVersion`** to separate IPv4 and IPv6 traffic in analytics. - **Check `isValid` first** before relying on any location or network field. - **Export Dataset as CSV** for BI tools, spreadsheets, or reporting dashboards. - **Use API access** to plug this Actor into fraud checks, log enrichment, and traffic analysis flows. ### FAQ #### Is IP Geolocation Lookup free? Free trial covers extensive testing. Production usage is pay-per-compute and typically low cost for normal bulk lookup workloads. #### Does it support both IPv4 and IPv6? Yes. The Actor validates and processes both IPv4 and IPv6 addresses. #### What happens if an IP is invalid? `isValid` returns `false`, `ipVersion` returns `null`, and `location` returns `null`. If `includeNetwork` is enabled, `network` also returns `null`. #### Do I need `includeNetwork` for geolocation? No. Geolocation works without it. `includeNetwork` is only needed when you want ISP, ASN, and organization enrichment. #### What does ASN mean? ASN stands for **Autonomous System Number**. It identifies the network or routing domain associated with an IP address. #### Can I use this for bulk analytics or fraud checks? Yes. This Actor is well suited for log enrichment, traffic analysis, geo-targeting, suspicious IP review, and network-based segmentation. *** **Feedback?** [Create issue](https://apify.com/apizy/ip-geolocation-lookup/issues/open) — open to suggestions! # Actor input Schema ## `ips` (type: `array`): List of IPv4 or IPv6 addresses to lookup. ## `includeNetwork` (type: `boolean`): Include ISP, ASN, and organization data in the output. ## Actor input object example ```json { "ips": [ "8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999" ], "includeNetwork": false } ``` # Actor output Schema ## `results` (type: `string`): Dataset containing IP geolocation lookup results ## `output` (type: `string`): IP geolocation lookup results from key-value store OUTPUT # 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": [ "8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999" ] }; // Run the Actor and wait for it to finish const run = await client.actor("apizy/ip-geolocation-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": [ "8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999", ] } # Run the Actor and wait for it to finish run = client.actor("apizy/ip-geolocation-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": [ "8.8.8.8", "1.1.1.1", "2001:4860:4860::8888", "999.999.999.999" ] }' | apify call apizy/ip-geolocation-lookup --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=apizy/ip-geolocation-lookup", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/acts/h2kQToGUp1UY8myce/builds/bysOGs3HnO2xuHyAF/openapi.json