IP2Proxy Getting Started: Quickstart Guide (2026)

Getting started overview

IP2Proxy provides services for detecting proxy, VPN, and anonymizer usage based on an IP address. You can integrate IP2Proxy functionality either through a Web Service API or by downloading and hosting local databases. This guide focuses on the initial steps for both methods, specifically account creation, credential acquisition, and making a first successful request.

The Web Service offers real-time lookups without requiring local data management, while databases provide faster local queries after an initial download and setup. Your choice depends on factors such as internet connectivity requirements, latency tolerance, and data update frequency. For detailed information on the various IP2Proxy products, consult the official IP2Proxy developer documentation.

Here's a quick reference table outlining the essential steps to get started:

Create an account and get keys

To begin using IP2Proxy, you must first create an account. This process is standard for most API providers and involves registration and verification. For access to the Web Service, an API key is required. For database integration, you will download specific database files after account creation.

Account Creation

1. Navigate to the IP2Proxy developer page.
2. Locate the option to register for a new account. You'll typically provide an email address and set a password.
3. Verify your email address, if prompted, by clicking a link sent to your inbox.
4. Log in to your newly created IP2Proxy account.

Obtaining Credentials (API Key or Database Files)

For Web Service API:

After logging in, your API key will generally be displayed in your account dashboard or a dedicated 'API Key' section. This key authenticates your requests to the IP2Proxy Web Service.

• Locate your unique API key in your IP2Proxy account dashboard.
• Keep this key secure and do not expose it in client-side code or public repositories.

For Local Databases:

If you opt for database integration, you will download the relevant database files from your account dashboard. IP2Proxy offers various database packages (PX1-PX11), each containing different levels of data detail. A free LITE database is also available for basic testing.

• From your account dashboard, navigate to the database download section.
• Select the desired database package (e.g., PX1 for proxy type, or the Free LITE database).
• Download the database file (e.g., IP2PROXY-PX1.BIN).
• Store the database file in a location accessible by your application.

Your first request

Making your first request verifies your setup and credentials. We'll cover both the Web Service API and a basic local database query.

Web Service API Example (Python)

This example demonstrates how to query the IP2Proxy Web Service using Python to detect if an IP address is a proxy. Replace YOUR_API_KEY with your actual API key and TARGET_IP_ADDRESS with the IP you wish to query.

import requests

API_KEY = "YOUR_API_KEY"
TARGET_IP = "8.8.8.8" # Example IP address (Google's Public DNS)

default_parameters = "PX1"
# You can customize fields to return, e.g., 'PX1,country_name,region_name' for more details.
# Refer to the IP2Proxy Web Service documentation for a full list of available fields.

url = f"https://api.ip2proxy.com/?key={API_KEY}&ip={TARGET_IP}&info={default_parameters}&format=json"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    
    print(f"Querying IP: {TARGET_IP}")
    if data and "proxyType" in data:
        if data["proxyType"] != "-":
            print(f"Proxy Detected: {data['proxyType']} ({data['countryName']})")
        else:
            print(f"No Proxy Detected for {TARGET_IP}")
        print(f"Full response: {data}")
    else:
        print("Error or unexpected response format.")
        print(f"Response: {data}")

except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

This Python script uses the requests library, a common HTTP client for Python, to send a GET request to the IP2Proxy Web Service. The response is parsed as JSON, and the proxyType field is checked to determine if a proxy is detected. For more details on URL parameters and response fields, consult the IP2Proxy Web Service API reference.

Local Database Example (Python with IP2Proxy Python SDK)

For local database integration, you'll need to install the relevant SDK for your language. This example uses the Python SDK.

1. Install the SDK:

   
   pip install IP2Proxy
   

2. Query the database: Replace path/to/IP2PROXY-PX1.BIN with the actual path to your downloaded database file.

import IP2Proxy

database_path = "path/to/IP2PROXY-PX1.BIN" # Update this path
TARGET_IP = "1.2.3.4" # Example IP address

try:
    # Initialize the IP2Proxy object with the database path
    # Use IP2Proxy.open(database_path, IP2Proxy.IP2PROXY_MMF) for Memory Mapped File access (recommended for performance)
    # or IP2Proxy.open(database_path) for standard file access
    
ip = IP2Proxy.open(database_path)
    
    # Query the IP address
    # The 'all' option retrieves all available fields for the database package
    result = ip.get_all(TARGET_IP)
    
    print(f"Querying IP: {TARGET_IP}")
    if result.proxy_type != "-":
        print(f"Proxy Detected: {result.proxy_type} ({result.country_name})")
    else:
        print(f"No Proxy Detected for {TARGET_IP}")
    
    print(f"Full result: ")
    print(f"  IP Number: {result.ip_number}")
    print(f"  Country Code: {result.country_code}")
    print(f"  Country Name: {result.country_name}")
    print(f"  Region Name: {result.region_name}")
    print(f"  City Name: {result.city_name}")
    print(f"  ISP: {result.isp}")
    print(f"  Domain: {result.domain}")
    print(f"  Usage Type: {result.usage_type}")
    print(f"  ASN: {result.asn}")
    print(f"  AS Name: {result.as_name}")
    print(f"  Last Seen: {result.last_seen}")
    print(f"  Threat: {result.threat}")
    print(f"Threat: {result.threat}")
    print(f"  Proxy Type: {result.proxy_type}")
    print(f"  Is Proxy: {result.is_proxy}")

except Exception as e:
    print(f"Error querying database: {e}")
finally:
    # Close the database file handle (important for resource management)
    if 'ip' in locals() and ip:
        ip.close()

This script initializes the IP2Proxy Python SDK with your downloaded database and then queries an IP address. The SDK provides methods to access various data fields depending on your database package. For more information on using the SDKs, refer to the IP2Proxy SDK documentation.

Common next steps

After successfully making your first request, consider these common next steps to further integrate IP2Proxy into your application:

• Explore Additional Data Fields: The IP2Proxy Web Service and databases offer various data fields beyond just proxy type, such as country, region, city, ISP, domain, usage type, ASN, and threat level. Review the Web Service API reference or database specifications to understand all available data points for your chosen package.
• Implement Error Handling: Robust applications include comprehensive error handling. For the Web Service, anticipate HTTP errors (e.g., 401 for invalid API key, 403 for rate limits) and network issues. For local databases, handle file access errors or corrupted database files.
• Integrate with Your Application Logic: Incorporate the proxy detection results into your application's business logic. For example, if a proxy is detected, you might block the request, prompt for additional verification, or route the user to a specific content version.
• Optimize Performance (for databases): If using local databases, consider optimizing read performance. IP2Proxy offers memory-mapped file (MMF) access in some SDKs, which can significantly speed up lookups compared to standard file I/O.
• Monitor Usage and Billing: If using the Web Service, monitor your API usage against your plan limits to avoid unexpected charges or service interruptions. The IP2Proxy billing page provides details on usage-based pricing.
• Secure Your API Key: Ensure your API key is stored securely, ideally using environment variables or a secrets management service, particularly in production environments. An overview of API key security best practices is available from sources like Google Developers on API Key Security.
• Automate Database Updates (for databases): If using local databases, establish a process to regularly update your database files to ensure you have the latest proxy intelligence. IP2Proxy typically releases monthly updates.

Troubleshooting the first call

Encountering issues during your first API call or database query is common. Here are some troubleshooting steps:

• Check API Key Validity: Ensure your API key is correct and hasn't expired or been revoked. Double-check for typos or leading/trailing spaces.
• Verify Internet Connectivity: For Web Service calls, confirm your system has an active internet connection and can reach api.ip2proxy.com. Network firewalls or proxies might block outgoing requests.
• Review API Endpoint and Parameters: Confirm that the URL for the Web Service is correct (https://api.ip2proxy.com/) and that all required parameters (key, ip, info, format) are included and correctly formatted. Consult the IP2Proxy Web Service API reference for exact specifications.
• Examine Error Messages: The Web Service will return specific error messages in its JSON response (e.g., {"error":"Invalid API key"}). Read these messages carefully, as they often pinpoint the problem.
• Check Database File Path (for local databases): Ensure the path to your .BIN database file is absolutely correct and that your application has read permissions for that file and directory.
• Confirm Database File Integrity (for local databases): If the database file was corrupted during download, it might lead to errors. Try re-downloading the file from your IP2Proxy account.
• SDK Installation and Version: Verify that the IP2Proxy SDK for your language is correctly installed and that you are using a compatible version. Refer to the specific SDK documentation.
• Rate Limiting: If you are on a free or limited plan, you might hit rate limits. Check your account dashboard for current usage and limits.
• Contact Support: If you've exhausted other options, IP2Proxy offers support through their website. Provide them with relevant details, including your API key (if safe to share), the IP address queried, and any error messages received.