This example demonstrates how to generate a list of sticky residential proxies in the US for a specific proxy user using the /residential/list endpoint.

import requests

# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.pingproxies.com/1.0/public"

def get_residential_proxy_list(proxy_user_id):
    """Generate a list of sticky residential proxies in the US for a specific proxy user."""
    
    # Headers for authentication
    headers = {
        "X-API-Public-Key": API_PUBLIC_KEY,
        "X-API-Private-Key": API_PRIVATE_KEY
    }
    
    # Parameters for the residential proxy list
    params = {
        "proxy_user_id": proxy_user_id,  # The specific proxy user
        "country_id": "us",              # United States
        "list_session_type": "sticky",   # sticky session
        "list_count": 10,                # Number of proxies to generate
        "list_format": "socks5h"         # Proxy format
    }
    
    # Make request to the residential list endpoint
    response = requests.get(
        f"{BASE_URL}/user/residential/list",
        params=params,
        headers=headers
    )
    
    if response.status_code != 200:  # Note: This endpoint returns 200 Created
        print(f"Error: {response.status_code}")
        return None
    
    # Parse the response
    data = response.json()
    
    # Return the list of proxies
    return data["data"]

# Example usage
if __name__ == "__main__":
    # Replace with your actual proxy user ID
    proxy_user_id = "your_proxy_user_id"
    
    # Get the residential proxy list
    proxies = get_residential_proxy_list(proxy_user_id)
    
    if proxies:
        print(f"Successfully generated {len(proxies)} US residential proxies for user {proxy_user_id}")
        print("\nProxies:")
        for proxy in proxies:
            print(proxy)

Key Parameters Explained

When generating a residential proxy list for a specific user, you need to specify:

  • proxy_user_id: The ID of the specific proxy user who will authenticate with these proxies
  • country_id: The country code (in this case “us” for United States)
  • list_session_type: Set to “sticky” for sticky residential sessions
  • list_count: Number of proxies to generate
  • list_format: Format of the returned proxies (e.g., “socks5h”)

Expected Output Format

The API will return a list of ready-to-use proxy strings. For example, with list_format=socks5h:

socks5h://your_user_c_us_s_ABCDEFGHIJKLMNO:your_password@residential.pingproxies.com:8000
socks5h://your_user_c_us_s_PQRSTUVWXYZ1234:your_password@residential.pingproxies.com:8000

Important Notes

  • Unlike datacenter and ISP proxies, residential proxies are generated on-demand
  • The proxy user must have sufficient residential bandwidth allocation
  • Every request for residential proxies consumes a small amount of bandwidth
  • Each generated proxy contains location targeting information in its name