IP Geolocation Lookup

Look up geographic location, ISP details, and security flags for any list of IP addresses -- from one to tens of thousands. This Apify actor uses the ip-api.com batch endpoint to resolve IPv4 and IPv6 addresses into structured geolocation data including country, city, coordinates, timezone, ISP, autonomous system info, and proxy/VPN/hosting detection flags. Feed it a handful of IPs or an entire server log's worth; the actor handles batching, deduplication, and rate limiting automatically so you can focus on using the data.

---

Why use IP Geolocation Lookup?

Knowing where an IP address is located and who operates it is fundamental to security operations, fraud detection, analytics, and compliance. Manually querying IPs one at a time does not scale. This actor lets you submit thousands of IPs in a single run and get structured, normalized results back in seconds.

Every result includes not just geographic coordinates but also ISP and organization names, autonomous system identifiers, and three critical boolean flags -- isProxy, isHosting, and isMobile -- that tell you whether the IP belongs to a VPN/proxy service, a cloud hosting provider, or a mobile carrier. These flags are essential for fraud scoring, bot detection, and traffic quality analysis.

The actor runs on Apify's cloud infrastructure, which means you can schedule it, trigger it via API, chain it with other actors, and export results to any format. No local setup, no API key management, no rate limit headaches -- just provide a list of IPs and go.

Whether you are enriching web server logs, validating user signups, auditing network traffic, or building a threat intelligence pipeline, this actor gives you clean, structured IP intelligence at scale without writing a single line of code.

---

Key features

• Batch processing -- Processes up to 100 IPs per API call using the ip-api.com batch endpoint, dramatically reducing lookup time for large lists.
• Automatic deduplication -- Duplicate IP addresses are removed via a Set before processing so you never waste time on redundant lookups.
• IPv4 and IPv6 support -- Works with both 8.8.8.8 (IPv4) and 2606:4700:4700::1111 (IPv6) addresses without any configuration changes.
• Proxy/VPN detection -- Each result includes isProxy, isHosting, and isMobile boolean flags to identify VPNs, cloud servers, Tor exit nodes, and mobile carriers.
• Reverse DNS lookup -- Optionally resolves the reverse hostname for each IP (e.g., dns.google for 8.8.8.8), enabled by default.
• Custom field selection -- Request only the fields you need to minimize output size and focus your analysis. The status and query fields are always included automatically.
• Built-in rate limiting -- Automatically spaces batches 1.5 seconds apart and handles HTTP 429 responses with a 60-second backoff and one automatic retry.
• 19 structured output fields -- Every result is normalized into a clean schema with descriptive field names (latitude/longitude instead of lat/lon), regardless of which fields the upstream API returns.
• Graceful failure handling -- Failed lookups (reserved IPs, invalid addresses) are included in output with status: "fail" so you can account for every input IP.
• Zero configuration -- No external API keys needed. Just provide a list of IPs and run.

---

How to use

Using the Apify Console

1. Navigate to the IP Geolocation Lookup actor page on Apify.
2. Click Try for free to open the actor in the Console.
3. In the IP Addresses field, enter your IP addresses one per line using the string list editor. The default prefill includes 8.8.8.8 and 1.1.1.1 for quick testing.
4. Optionally uncheck Include Reverse Hostname if you do not need reverse DNS data.
5. Optionally enter a comma-separated list in Fields to Include to limit the output (e.g., country,city,isp,proxy).
6. Click Start to run the actor.
7. When the run completes, view results in the Dataset tab. Export as JSON, CSV, Excel, or XML, or connect to any downstream integration.

Using the API

curl -X POST "https://api.apify.com/v2/acts/ryanclinton~ip-geolocation-lookup/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAddresses": ["8.8.8.8", "1.1.1.1", "208.67.222.222", "9.9.9.9"],
    "includeReverseHostname": true
  }'

The API returns a run object containing a defaultDatasetId. Fetch results with:

$curl "https://api.apify.com/v2/datasets/{DATASET_ID}/items?token=YOUR_API_TOKEN&format=json"

Replace {DATASET_ID} with the value from the run response. You can also use format=csv or format=xlsx for alternative export formats.

---

Input parameters

Name	Type	Required	Default	Description
ipAddresses	string[]	Yes	["8.8.8.8", "1.1.1.1"]	List of IPv4 or IPv6 addresses to look up. Duplicates are removed automatically before processing.
fields	string	No	All fields	Comma-separated list of ip-api.com fields to include. Available: country, countryCode, region, regionName, city, zip, lat, lon, timezone, isp, org, as, asname, reverse, mobile, proxy, hosting.
includeReverseHostname	boolean	No	true	Whether to perform a reverse DNS lookup and include the hostname in each result.

Example input (JSON):

{
    "ipAddresses": [
        "8.8.8.8",
        "1.1.1.1",
        "208.67.222.222",
        "9.9.9.9",
        "2606:4700:4700::1111"
    ],
    "fields": "country,city,isp,proxy,hosting,mobile",
    "includeReverseHostname": false
}

Tips:

• Leave the fields parameter empty to get all 19 output fields. The status and query (mapped to ip) fields are always included regardless of your selection.
• The actor automatically trims whitespace and removes empty strings from the IP list, so minor formatting issues will not cause failures.
• For large lists (10,000+ IPs), expect the run to take a few minutes due to rate limiting between batches. Each batch of 100 IPs takes approximately 1.5 seconds plus network round-trip time.

---

Output

Each IP address produces one object in the output dataset. Here is an example showing two results:

[
    {
        "ip": "8.8.8.8",
        "country": "United States",
        "countryCode": "US",
        "region": "VA",
        "regionName": "Virginia",
        "city": "Ashburn",
        "zip": "20149",
        "latitude": 39.03,
        "longitude": -77.5,
        "timezone": "America/New_York",
        "isp": "Google LLC",
        "organization": "Google Public DNS",
        "asNumber": "AS15169 Google LLC",
        "asName": "GOOGLE",
        "reverseHostname": "dns.google",
        "isMobile": false,
        "isProxy": false,
        "isHosting": true,
        "status": "success"
    },
    {
        "ip": "1.1.1.1",
        "country": "Australia",
        "countryCode": "AU",
        "region": "QLD",
        "regionName": "Queensland",
        "city": "South Brisbane",
        "zip": "4101",
        "latitude": -27.4766,
        "longitude": 153.0166,
        "timezone": "Australia/Brisbane",
        "isp": "Cloudflare, Inc",
        "organization": "APNIC and Cloudflare DNS Resolver project",
        "asNumber": "AS13335 Cloudflare, Inc",
        "asName": "CLOUDFLARENET",
        "reverseHostname": "one.one.one.one",
        "isMobile": false,
        "isProxy": false,
        "isHosting": true,
        "status": "success"
    }
]

Output field descriptions:

Field	Type	Description
ip	string	The queried IP address.
country	string	Full country name (e.g., "United States").
countryCode	string	ISO 3166-1 alpha-2 country code (e.g., "US").
region	string	Region/state code (e.g., "VA").
regionName	string	Full region/state name (e.g., "Virginia").
city	string	City name (e.g., "Ashburn").
zip	string	Postal/ZIP code.
latitude	number	Latitude coordinate.
longitude	number	Longitude coordinate.
timezone	string	IANA timezone identifier (e.g., "America/New_York").
isp	string	Internet Service Provider name.
organization	string	Organization name associated with the IP range.
asNumber	string	Autonomous System number and name (e.g., "AS15169 Google LLC").
asName	string	Autonomous System short name (e.g., "GOOGLE").
reverseHostname	string	Reverse DNS hostname (e.g., "dns.google"). Null if disabled or unavailable.
isMobile	boolean	Whether the IP belongs to a mobile carrier network.
isProxy	boolean	Whether the IP is a known proxy, VPN, or Tor exit node.
isHosting	boolean	Whether the IP belongs to a hosting or data center provider.
status	string	"success" or "fail". Failed lookups include the IP but all other fields are null.

---

Use cases

• Fraud detection -- Flag user signups or transactions coming from known proxy/VPN addresses or hosting providers that typically indicate automated or fraudulent activity.
• Web analytics enrichment -- Enrich server access logs with geographic data to understand where your visitors are actually located, beyond what browser-based analytics provide.
• Ad fraud prevention -- Identify clicks and impressions originating from data centers (isHosting: true) or proxy networks (isProxy: true) to filter invalid traffic from your ad campaigns.
• Compliance and geo-fencing -- Verify that users accessing your service are located in permitted jurisdictions by checking country codes against your allow/deny lists.
• Threat intelligence -- Build IP reputation databases by cross-referencing geolocation data with known malicious IP lists, autonomous system information, and proxy detection flags.
• Email security -- Analyze originating IP addresses from email headers to detect phishing attempts from unexpected geographic locations or hosting providers.
• Network forensics -- Investigate security incidents by mapping attacker IPs to geographic locations, ISPs, and autonomous systems for attribution and reporting.
• Content delivery optimization -- Analyze your user base distribution across countries and regions to make informed decisions about CDN node placement and server locations.
• Bot detection -- Combine the isProxy, isHosting, and isMobile flags with traffic patterns to build scoring models that distinguish legitimate users from automated bots.

---

API & integration

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run_input = {
    "ipAddresses": ["8.8.8.8", "1.1.1.1", "208.67.222.222"],
    "includeReverseHostname": True,
}

run = client.actor("ryanclinton/ip-geolocation-lookup").call(run_input=run_input)

dataset_items = client.dataset(run["defaultDatasetId"]).list_items().items
for item in dataset_items:
    print(f"{item['ip']} -> {item['city']}, {item['country']} "
          f"(Proxy: {item['isProxy']}, Hosting: {item['isHosting']})")

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const input = {
    ipAddresses: ['8.8.8.8', '1.1.1.1', '208.67.222.222'],
    includeReverseHostname: true,
};

const run = await client.actor('ryanclinton/ip-geolocation-lookup').call(input);

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.log(`${item.ip} -> ${item.city}, ${item.country} `
        + `(Proxy: ${item.isProxy}, Hosting: ${item.isHosting})`);
});

cURL

# Start the actor run
curl -X POST "https://api.apify.com/v2/acts/ryanclinton~ip-geolocation-lookup/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ipAddresses": ["8.8.8.8", "1.1.1.1", "208.67.222.222"],
    "includeReverseHostname": true
  }'

# Fetch results (replace DATASET_ID with defaultDatasetId from the run response)
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_API_TOKEN&format=json"

This actor integrates with the full Apify ecosystem. Connect it to Zapier, Make (Integromat), Google Sheets, Slack, or GitHub Actions using Apify's built-in integrations. You can also chain it with other actors via webhooks or the Apify API to build automated IP intelligence pipelines.

---

How it works

1. Input validation -- The actor reads the ipAddresses array from input and verifies it is a non-empty array. It also reads the optional fields and includeReverseHostname parameters.
2. Deduplication and cleaning -- All IP addresses are trimmed of whitespace, empty strings are filtered out, and duplicates are eliminated using a JavaScript Set to avoid redundant lookups.
3. Field parameter construction -- The actor builds a comma-separated field selection string for the ip-api.com batch API. If custom fields are provided, status and query are always injected to ensure proper result mapping. If the includeReverseHostname flag is true, the reverse field is appended. When no custom fields are specified, all 19 available fields are requested.
4. Batch processing -- The deduplicated IP list is split into chunks of 100 (the ip-api.com batch endpoint maximum). Each chunk is sent as a POST request to http://ip-api.com/batch with a JSON body containing an array of { query, fields } objects.
5. Rate limit management -- A 1.5-second delay is enforced between consecutive batch requests to stay under the ~45 requests/minute limit. If the API returns HTTP 429, the actor waits 60 seconds and retries the batch once before throwing an error.
6. Result transformation -- Raw ip-api.com responses are mapped to a clean, normalized output schema. Field names are converted from API shorthand (lat/lon/org/as) to descriptive names (latitude/longitude/organization/asNumber). Failed lookups are preserved with null fields and status: "fail".
7. Dataset push -- All transformed results are pushed to the Apify dataset in a single call, ready for export in JSON, CSV, Excel, XML, or any other supported format.

IP Geolocation Lookup Pipeline

+------------------+     +------------------+     +-------------------+
|  Input: IP List  | --> |  Deduplicate &   | --> |  Build fields     |
|  (ipAddresses)   |     |  clean via Set   |     |  parameter string |
+------------------+     +------------------+     +-------------------+
                                                          |
                                                          v
+------------------+     +------------------+     +-------------------+
|  Push all results| <-- |  Transform to    | <-- |  POST batches of  |
|  to Apify dataset|     |  output schema   |     |  100 to ip-api.com|
+------------------+     +------------------+     +-------------------+
                                                  (1.5s delay between)
                                                  (60s backoff on 429)

---

Performance & cost

Metric	Details
Batch size	100 IPs per API request (ip-api.com batch endpoint maximum).
Throughput	Approximately 4,000 IPs per minute under normal conditions (100 IPs every ~1.5 seconds).
Memory usage	256 MB default allocation -- sufficient for lists of 100,000+ IPs.
Run cost	Minimal. A run processing 1,000 IPs completes in under 30 seconds and costs fractions of a cent in Apify compute units.
Rate limiting	1.5-second delay between batches. Automatic 60-second backoff with one retry on HTTP 429 responses.
External API cost	None. Uses the free ip-api.com batch endpoint with no API key or subscription required.

---

Limitations

• ip-api.com rate limits -- The free tier allows approximately 45 batch requests per minute. The actor respects this with built-in delays, but very large runs (100,000+ IPs) will take proportionally longer due to throttling.
• Geolocation accuracy -- IP geolocation is inherently approximate. Country-level accuracy is typically 99%+, but city-level accuracy ranges from 50-80% depending on region and ISP. Coordinates should be treated as estimates, not precise locations.
• Private and reserved IPs -- Addresses in private ranges (e.g., 10.0.0.0/8, 192.168.0.0/16, 127.0.0.1) and other reserved blocks will return status: "fail" with null geolocation fields.
• Single retry on rate limit -- If ip-api.com returns HTTP 429, the actor waits 60 seconds and retries once. If the retry also fails, the run terminates with an error.
• No historical data -- Results reflect the current state of IP geolocation databases. IP assignments change over time, so results for the same IP may differ between runs weeks or months apart.
• Proxy detection coverage -- The isProxy flag catches many known VPNs, proxies, and Tor exit nodes, but no database is 100% complete. Newly launched proxy services may not be flagged immediately.
• Upstream dependency -- The actor depends on the ip-api.com service availability. If their API is down or unreachable, the actor run will fail.

---

Responsible use

• Respect privacy regulations -- IP addresses can constitute personal data under GDPR, CCPA, and similar regulations. Ensure you have a lawful basis for processing IP geolocation data and that your use complies with applicable privacy laws in your jurisdiction.
• Do not use for harassment or stalking -- IP geolocation provides approximate location data at best. Never use this information to track, harass, or surveil individuals. City-level geolocation is not precise enough to identify a specific person or physical address.
• Respect ip-api.com terms of service -- This actor uses the free ip-api.com batch endpoint. Review their terms of service to ensure your use case is permitted, particularly for high-volume commercial applications.
• Secure your output data -- Geolocation results may contain sensitive intelligence about your infrastructure, users, or investigation targets. Store and transmit results securely, and limit access to authorized personnel.
• Avoid unnecessary re-lookups -- While the actor handles rate limiting automatically, avoid scheduling excessively frequent runs with the same IP lists. Cache results when the data does not need to be refreshed in real time.

---

FAQ

Q: Do I need an API key to use this actor? A: No. The actor uses the free ip-api.com batch endpoint, which requires no API key or registration. You only need an Apify account and API token to run the actor itself.

Q: How many IPs can I look up in a single run? A: There is no hard limit on input size. The actor processes IPs in batches of 100 with a 1.5-second delay between batches. Approximately 1,000 IPs completes in under 30 seconds, 10,000 IPs takes about 3-4 minutes, and 100,000+ IPs is supported but will take proportionally longer.

Q: Does it support IPv6 addresses? A: Yes. Both IPv4 (e.g., 8.8.8.8) and IPv6 (e.g., 2606:4700:4700::1111) addresses are fully supported and can be mixed in the same input list.

Q: What happens if I submit duplicate IPs? A: Duplicates are automatically removed before processing using a JavaScript Set. If you submit ["8.8.8.8", "8.8.8.8", "1.1.1.1"], only two lookups are performed and two results are returned.

Q: What does the isProxy flag detect? A: The isProxy flag indicates whether the IP is a known VPN endpoint, public proxy server, or Tor exit node. It is based on ip-api.com's detection database, which covers major VPN providers, public proxy lists, and the Tor network.

Q: What is the difference between isProxy and isHosting? A: isProxy identifies IPs actively used as VPN or proxy endpoints. isHosting identifies IPs belonging to data center and cloud hosting providers (e.g., AWS, Google Cloud, DigitalOcean) regardless of whether they are used as proxies. An IP can have both flags set to true.

Q: Why do some IPs return status: "fail"? A: IPs in private ranges (10.x.x.x, 192.168.x.x, 172.16-31.x.x), loopback addresses (127.0.0.1), and other reserved blocks cannot be geolocated by ip-api.com. Invalid strings that are not valid IP addresses will also fail. The actor logs a warning for each failure but continues processing.

Q: Can I get only specific fields to reduce output size? A: Yes. Use the fields input parameter with a comma-separated list like country,city,isp,proxy. The status and ip fields are always included in the output regardless of your field selection.

Q: How accurate is the geolocation data? A: Accuracy varies by region and ISP. Country-level accuracy is typically 99%+. City-level accuracy ranges from 50-80%. Coordinates are approximate and should not be used for precise location determination. Data is sourced from ip-api.com's regularly updated geolocation databases.

Q: What happens if ip-api.com rate limits my run? A: The actor automatically detects HTTP 429 responses, pauses for 60 seconds, and retries the failed batch once. The built-in 1.5-second delay between batches is designed to stay within the ~45 requests/minute limit under normal conditions.

Q: Can I schedule this actor to run on a recurring basis? A: Yes. Use Apify's built-in scheduler to run the actor at any interval -- hourly, daily, weekly, or on a custom cron expression. Combine it with webhooks to automatically process new results downstream.

Q: What is the reverseHostname field? A: It is the result of a reverse DNS (PTR record) lookup on the IP address. For example, 8.8.8.8 resolves to dns.google and 1.1.1.1 resolves to one.one.one.one. This can help identify the service or organization behind an IP. Set includeReverseHostname to false if you do not need this data.

---

Related actors

Actor	Description	Link
DNS Record Lookup	Query DNS records (A, AAAA, MX, TXT, CNAME, NS, SOA) for any domain name.	DNS Record Lookup
SSL Certificate Search	Search crt.sh Certificate Transparency logs to discover subdomains and certificate history for any domain.	SSL Certificate Search
WHOIS Domain Lookup	Look up WHOIS registration data for domains including registrar, dates, nameservers, and contact info.	WHOIS Domain Lookup
Censys Internet Host Search	Search Censys for internet-connected hosts, open ports, running services, and TLS certificates.	Censys Internet Host Search
CISA KEV Catalog	Search the CISA Known Exploited Vulnerabilities catalog for actively exploited security flaws.	CISA KEV Catalog
NVD CVE Vulnerability Search	Search the NIST National Vulnerability Database for CVEs by keyword, severity, or date range.	NVD CVE Vulnerability Search