The Ping Proxies API organizes resources in a hierarchical structure that mirrors the real-world relationships between network and geographic entities. Understanding these relationships is crucial for effectively managing and filtering proxies.

​
Geographic Hierarchy

Continent > Country > Subdivision > City

This hierarchical structure allows you to target proxies at different geographic levels:

  • Continent: The broadest geographic division (e.g., eu for Europe)
  • Country: Countries within continents (e.g., fr for France)
  • Subdivision: States, provinces, regions (e.g., fr-idf for Île-de-France)
  • City: Specific cities (e.g., paris with city_id 379657)

​
Network Hierarchy

ASN > Subnet > IP Address > Proxy
  • ASN (Autonomous System Number): Identifies a network operator like AT&T (ASN 7018)
  • Subnet: A range of IP addresses (e.g., 107.225.72.0/22)
  • IP Address: The specific address assigned to a proxy
  • Proxy: The actual proxy service with ports and authentication

​
How Objects Connect

​
Proxy Objects

A proxy object represents a single proxy instance. It connects to both geographic and network hierarchies:

{
  "proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
  "proxy_ip_address": "107.225.73.142",
  "proxy_http_port": 8080,
  "proxy_socks5_port": 1080,
  "proxy_type": "isp",
  "proxy_protocol": "ipv4",
  "proxy_status": "in_use",
  
  // Network hierarchy connections
  "asn_id": 7018,
  "asn_name": "AT&T Enterprises, LLC",
  "subnet_id": "107.225.72.0/22",
  
  // Geographic hierarchy connections
  "country_id": "us",
  "country_name": "United States",
  "subdivision_id": "us-tx",
  "subdivision_name": "Texas",
  "city_id": 75202,
  "city_name": "Dallas",
  "city_timezone": "America/Chicago",
  "city_latitude": 32.7767,
  "city_longitude": -96.797
}

​
Service Objects and Proxies

Services are container objects that group proxies:

Service > Proxies

A service represents a purchased group of proxies, and may contain multiple proxy objects:

{
  "service_id": "API-1234-5678",
  "service_name": "AT&T ISP Proxies [US]",
  "service_type": "isp",
  "service_protocol": "ipv4",
  "service_quantity": 5,
  "service_status": "active",
  "country_id": "us",
  
  // Service may contain multiple proxies
  "proxies": [
    {
      "proxy_id": "7a018d34-76c2-4c23-b14d-f7b9a7054e25",
      "proxy_ip_address": "107.225.73.142",
      // Additional proxy details...
    },
    // More proxies...
  ]
}

​
Residential Proxy Generation and Object Relationships

Residential proxies differ from datacenter and ISP proxies in that they’re generated on demand rather than being persistent objects. When generating residential proxies, you specify geographic and network attributes to target specific types of exit nodes.

​
Residential Proxy Example

# Generate 5 residential proxies in London, UK
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/residential/list?country_id=gb&city_alias=london&list_count=5' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

Response:

{
  "data": [
    "socks5h://stevejobs_c_gb_city_london_s_DDINPY7TQ0781XEO:apple1984@residential.pingproxies.com:8000",
    "socks5h://stevejobs_c_gb_city_london_s_XIINPY7TQ0781XEA:apple1984@residential.pingproxies.com:8000",
    "socks5h://stevejobs_c_gb_city_london_s_PPINPY7TQ0781XEB:apple1984@residential.pingproxies.com:8000",
    "socks5h://stevejobs_c_gb_city_london_s_QQINPY7TQ0781XEC:apple1984@residential.pingproxies.com:8000",
    "socks5h://stevejobs_c_gb_city_london_s_RRINPY7TQ0781XED:apple1984@residential.pingproxies.com:8000"
  ],
  "message": "Residential list successfully created."
}

Notice that the geographic attributes (country_id and city_alias) are encoded in the proxy strings.

​
Filtering by ASN for Residential Proxies

While not shown in the basic example above, you can also filter residential proxies by ASN:

# Generate 3 residential proxies on Comcast's network (ASN 7922) in the US
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/residential/list?country_id=us&asn_id=7922&list_count=3' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

​
Practical Use Cases for Object Relationships

​
City-Based Targeting for Market Research

If you’re conducting market research for a new retail location, you might want to check product availability and pricing from the perspective of consumers in specific cities:

# Generate proxies in multiple target cities
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/residential/list?city_alias=new_york&list_count=2' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/residential/list?city_alias=chicago&list_count=2' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

​
ASN-Based Targeting for Ad Verification

For ad verification work, you might need to verify that ads are correctly displayed to users on specific ISPs:

# Find all available ISP proxies on AT&T's network
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/proxy/search?proxy_type=isp&asn_id=7018' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

This ensures that the proxies allocated to your service match your specific geographic and network requirements.

​
Exploring Available Options

To explore the available ASNs, countries, subdivisions, and cities, you can use the corresponding search endpoints:

# List all available ASNs
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/asn/search' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

# List all cities in a specific country
curl --request GET \
  --url 'https://api.pingproxies.com/1.0/public/user/city/search?country_id=gb' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

By understanding these object relationships, you can more effectively utilize the Ping Proxies API to precisely target and manage your proxy infrastructure according to your specific needs.