| API: plan | This API call provides a simple response about the current plan of the account. |
|---|---|
| Example | http://us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=plan&extended |
| Description | This API call provides a simple response about the current plan of the account. It should be used once when starting up your tool to check if the account is active and how many IP addresses are available. |
| Parameters | &extended=: optional |
| Responses | PLAN:$IP_IN_PLAN:$IP_COUNT: $IP_IN_PLAN defines the number of IPs in the plan. $IP_COUNT defines the number of IPs assigned. PLAN:$IP_IN_PLAN:$IP_COUNT:$PROXY_PROTOCOL:$PROXY_MAX_PROCESSES: The extended response includes the protocol and the highest number of processes to be started at the same time. ERROR:$NUMBER:$TEXT: Error, $NUMBER defines the error, $TEXT adds a human readable error description |
| API: rotate | This API call will rotate to a new IP address within your dedicated pool of IPs. |
|---|---|
| Example | http://us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=rotate |
| Description | This API call will rotate to a new IP address within your dedicated pool of IPs. Parameters are optional and allow to define the behaviour. This command will start your proxy if none is running and it updates the dynamic IP authentication with each call. |
| Parameters | &ip=: optional &process=: optional &randomize=: optional |
| Responses | ROTATE:$IP_CONNECTION:$PORT:$IP_ADDRESS: Successful rotation, connect to $IP_CONNECTION on port $PORT. ERROR:$NUMBER:$TEXT: Error, $NUMBER defines the error, $TEXT adds a human readable error description |
| API: ip_auth | The API is queried for the current authentication IP address |
|---|---|
| Example | http://us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=ip_auth |
| Description | The API is queried for the current authentication IP address |
| Parameters | |
| Responses | $IP_ADDRESS: Current authentication IP address. |
| API: status | Returns a general status about the current plan usage. |
|---|---|
| Example | http://us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=status |
| Description | Returns a general status about the current plan usage. If proxies are started this command will return one additional line per proxy process. |
| Parameters | &human=: optional |
| Responses | STATUS_RUNNING:$RUNNING: Returns the $RUNNING number of proxies. $RUNNING will be 0 if no proxy is started. STATUS_PROXY:$IP_ADDRESS:$IP_CONNECTION:$PORT:$TYPE:$INFO:$SEC_LAST_USAGE:$SEC_EXPIRE: Returns the proxy IP address, the connection IP address, the connection port number, |
| API: proxy_protocol | Set the proxy protocol, this API call makes sense for development of commercial API support for applications. |
|---|---|
| Example | http://us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=proxy_protocol |
| Description | Set the proxy protocol, this API call makes sense for development of commercial API support for applications. |
| Parameters | &protocol=:
|
| Responses | PROXY_PROTOCOL:CHANGED:Information: The protocol has been changed successfully ERROR:$NUMBER:$TEXT: Error, $NUMBER defines the error, $TEXT adds a human readable error description |
<? /*
* This is the API function to retrieve US IP addresses
* This function handles the API calls "plan" and "rotate"
*
* Rotate: On success this function will define the global $PROXY variable, adding the elements ready,address,port,external_ip and return 1
* On failure the return is 0 or smaller and the PROXY variable ready element is set to "0"
* It is good practice to use the API response in $PROXY instead of hardcoding connection parameters
*
* Plan: On success this function will define the global $PLAN variable, adding the elements active, max_ips, total_ips, protocol, processes and return 1
* It is good practice to make one call to "plan" upon starting your script to find out about the status and size of the plan
*/
function extractBody($response_str)
{
$parts = preg_split('|(?:\r?\n){2}|m', $response_str, 2);
if (isset($parts[1])) return $parts[1]; else return '';
}
function ip_service($cmd, $x = "")
{
global $pwd;
global $uid;
global $PROXY;
global $PLAN;
//$NL = '<br>\n';
$NL = '\n';
$fp = fsockopen("us-proxies.com", 80);
if (!$fp)
{
echo "Unable to connect to API $NL";
return -1; // connection not possible
} else
{
if ($cmd == "plan")
{
fwrite($fp, "GET /api.php?api=1&uid=$uid&pwd=$pwd&cmd=plan&extended=1 HTTP/1.0\r\nHost: us-proxies.com\r\nAccept: text/html, text/plain, text/*, */*;q=0.01\r\nAccept-Encoding: plain\r\nAccept-Language: en\r\n\r\n");
stream_set_timeout($fp, 8);
$res = "";
$n = 0;
while (!feof($fp))
{
if ($n++ > 4) break;
$res .= fread($fp, 8192);
}
$info = stream_get_meta_data($fp);
fclose($fp);
if ($info['timed_out'])
{
echo 'API: Connection timed out! $NL';
$PLAN['active'] = 0;
return -2; // api timeout
} else
{
if (strlen($res) > 1000) return -3; // invalid api response (check the API website for possible problems)
$data = extractBody($res);
$ar = explode(":", $data);
if (count($ar) < 4) return -100; // invalid api response
switch ($ar[0])
{
case "ERROR":
echo "API Error: $res $NL";
$PLAN['active'] = 0;
return 0; // Error received
break;
case "PLAN":
$PLAN['max_ips'] = $ar[1]; // number of IPs licensed
$PLAN['total_ips'] = $ar[2]; // number of IPs assigned
$PLAN['protocol'] = $ar[3]; // current proxy protocol (http, socks, ..)
$PLAN['processes'] = $ar[4]; // number of available proxy processes
if ($PLAN['total_ips'] > 0) $PLAN['active'] = 1; else $PLAN['active'] = 0;
return 1;
break;
default:
echo "API Error: Received answer $ar[0], expected \"PLAN\"";
$PLAN['active'] = 0;
return -101; // unknown API response
}
}
} // cmd==plan
if ($cmd == "rotate")
{
$PROXY['ready'] = 0;
fwrite($fp, "GET /api.php?api=1&uid=$uid&pwd=$pwd&cmd=rotate&randomize=0&offset=0 HTTP/1.0\r\nHost: us-proxies.com\r\nAccept: text/html, text/plain, text/*, */*;q=0.01\r\nAccept-Encoding: plain\r\nAccept-Language: en\r\n\r\n");
stream_set_timeout($fp, 8);
$res = "";
$n = 0;
while (!feof($fp))
{
if ($n++ > 4) break;
$res .= fread($fp, 8192);
}
$info = stream_get_meta_data($fp);
fclose($fp);
if ($info['timed_out'])
{
echo 'API: Connection timed out! $NL';
return -2; // api timeout
} else
{
if (strlen($res) > 1000) return -3; // invalid api response (check the API website for possible problems)
$data = extractBody($res);
$ar = explode(":", $data);
if (count($ar) < 4) return -100; // invalid api response
switch ($ar[0])
{
case "ERROR":
echo "API Error: $res $NL";
return 0; // Error received
break;
case "ROTATE":
$PROXY['address'] = $ar[1];
$PROXY['port'] = $ar[2];
$PROXY['external_ip'] = $ar[3];
$PROXY['ready'] = 1;
usleep(230000); // additional time to avoid connecting during proxy bootup phase, removing this can cause random connection failures but will increase overall performance for large IP licenses
return 1;
break;
default:
echo "API Error: Received answer $ar[0], expected \"ROTATE\"";
return -101; // unknown API response
}
}
} // cmd==rotate
}
}
/*
* This function is used to verify your proxy is working and it is a minimal code example on how to use the proxy through PHP and libcURL
* The function will use the currently configured proxy to query our ip check service.
* Please note we permit one ip check per rotation and access is restricted to customers.
* Except for minimal use cases of developers
*/
function getip()
{
global $PROXY;
if (!$PROXY['ready']) return -1; // proxy not ready
$curl_handle = curl_init();
curl_setopt($curl_handle, CURLOPT_URL, 'http://ipcheck.ipnetic.com/remote_ip.php'); // returns the real IP
curl_setopt($curl_handle, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($curl_handle, CURLOPT_TIMEOUT, 10);
curl_setopt($curl_handle, CURLOPT_RETURNTRANSFER, 1);
$curl_proxy = "$PROXY[address]:$PROXY[port]";
curl_setopt($curl_handle, CURLOPT_PROXY, $curl_proxy);
$tested_ip = curl_exec($curl_handle);
if (preg_match("^([1-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(\.([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])){3}^", $tested_ip))
{
curl_close($curl_handle);
return $tested_ip;
} else
{
$info = curl_getinfo($curl_handle);
curl_close($curl_handle);
return 0; // possible error would be a wrong authentication IP or a firewall
}
}
Abusive or wrong use of our IP service will be automatically as well as manually checked
by our servers and administration team.
Depending on the offense or error on your server/script/program there can be different means
of automated responses.
Delays The API server may decide to delay the next response for 10-20 seconds.
Throttle After continued overusage or high bursts (DoS like behaviour) the API can enable a 'Delay' for several hours.
Reject Some TOS violations can be detected and met with 'reject' bans on your proxy process or the whole user account.
This will result in your proxy process not answering anymore.
Depending on the severity or number of incidents the API server can block access to a proxy process for up to 5 hours.
One example would be captcha/virus warning pages from Google or Bing, this will result in automated temporal 'rejection' bans
to protect both sides from damage.
The first incident will be ignored to give your own tools a chance for correct action,
further incidents will result in bans from 30 minutes to 5 hours.
While the API can handle several types of abuse/script errors it is still your responsibility to make sure your tools
are running correctly.
Continued API bans/blocks will alert our administration staff, please try to avoid this.