Take full automated control of your Plan

Easy Proxy Automation through our HTTP API

HTTP API

For online APIs, HTTP is the most simple and accessible protocol.
One of the main benefits is that the programmer does not require to implement and understand a third party library.
Almost any programming language and operating system offer multiple ways to make HTTP requests and that is all you need to access our API.

Acessing and Controlling your Proxy Plan through the API


Credentials

With each API request you will include your credentials.
The credentials consist of an identification number and an encrypted password.

You are not logged in or do not own an active Plan.
Once you are logged in and own an active Plan you will find your identification and password here.
For demonstration purposes we will use the ID uid=0 and the password pwd=EncryptedPassword

API request syntax

$uid=0;
$pwd=EncryptedPassword;
$cmd="command";

Base syntax: http://www.us-proxies.com/api.php?api&uid=$uid&pwd=$pwd&cmd=$cmd

The first part of the HTTP request will always stay the same, it is used to authenticate with the API.
The cmd parameter specifies the API function you wish to call.
API functions often support additional parameters which are added in the same HTTP GET specific manner.

API request and response

This is a typical simple API call and the response.
Request:
http://us-proxies.com/api.php?api&uid=24312&pwd=a6e312252673f2e6138c413164d1ae5f&cmd=plan&extended
Parameters:
api -> enables API
uid:24312 -> user credential ID
pwd:a6e312252673f2e6138c413164d1ae5f -> user credential password
cmd:plan -> command to execute
extended -> additional parameter specific to this command
API response:
PLAN:15:15:http:1
The response is made up of one or more parts almost always separated by colons (:)
If the first part is either ERROR or the repeated COMMAND in uppercase letters.
If the response starts by ERROR it is followed by an error number and a descriptive error text.
In this particular case the command returned successfully.
The API answered that this plan has 15 IP addresses assigned, is set to the HTTP proxy protocol and one proxy process can be controlled.

Commands

API: planThis API call provides a simple response about the current plan of the account.
Examplehttp://www.us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=plan&extended
DescriptionThis 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
Type: boolean [0,1]
Receive extended information (proxy protocol and max proxy processes).
Default: 0


ResponsesPLAN:$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: rotateThis API call will rotate to a new IP address within your dedicated pool of IPs.
Examplehttp://www.us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=rotate
DescriptionThis 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
Type: IP address as a string value
Rotate to a specified IP address, if this IP is not within your pool default behaviour will take place.
Default: choose an available IP from your pool.


&process=:

optional
Type: Number [1-100]
Control a specific proxy process.
Default: control proxy process 1


&randomize=:

optional
Type: Number [0,1,2]
0 .. take IP addresses reverse sorted by their last activation time.
1 .. take IP addresses reverse sorted by their last activation time with randomization within the last 5 hours
2 .. take IP address randomized from your pool.
Default: 0


ResponsesROTATE:$IP_CONNECTION:$PORT:$IP_ADDRESS:

Successful rotation, connect to $IP_CONNECTION on port $PORT.
The proxy will provide the IP address $IP_ADDRESS


ERROR:$NUMBER:$TEXT:

Error, $NUMBER defines the error, $TEXT adds a human readable error description


API: ip_authThe API is queried for the current authentication IP address
Examplehttp://www.us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=ip_auth
DescriptionThe API is queried for the current authentication IP address
Parameters
Responses$IP_ADDRESS:

Current authentication IP address.
This API call does not respond by repeating the command with colon.


API: statusReturns a general status about the current plan usage.
Examplehttp://www.us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=status
DescriptionReturns 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
Type: [0,1]
Change parseable output into human readable output.
Default: 0


ResponsesSTATUS_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,
the proxy protocol, proxy information, seconds since start, seconds until termination.


API: proxy_protocolSet the proxy protocol, this API call makes sense for development of commercial API support for applications.
Examplehttp://www.us-proxies.com/api.php?api&uid=0&pwd=EncryptedPassword&cmd=proxy_protocol
DescriptionSet the proxy protocol, this API call makes sense for development of commercial API support for applications.
Parameters&protocol=:


Type: String [http,socks]
Changes the proxy protocol to HTTP or SOCKS.
The change will be applied at the next IP rotation.


ResponsesPROXY_PROTOCOL:CHANGED:Information:

The protocol has been changed successfully


ERROR:$NUMBER:$TEXT:

Error, $NUMBER defines the error, $TEXT adds a human readable error description



Source Code Examples

PHP API source code and minimal usage example


<?  /*
     * 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_str2);
        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($fp8);
                
$res "";
                
$n 0;
                while (!
feof($fp))
                {
                    if (
$n++ > 4) break;
                    
$res .= fread($fp8192);
                }
                
$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($fp8);
                
$res "";
                
$n 0;
                while (!
feof($fp))
                {
                    if (
$n++ > 4) break;
                    
$res .= fread($fp8192);
                }
                
$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_handleCURLOPT_URL'http://ipcheck.ipnetic.com/remote_ip.php'); // returns the real IP
        
curl_setopt($curl_handleCURLOPT_CONNECTTIMEOUT10);
        
curl_setopt($curl_handleCURLOPT_TIMEOUT10);
        
curl_setopt($curl_handleCURLOPT_RETURNTRANSFER1);
        
$curl_proxy "$PROXY[address]:$PROXY[port]";
        
curl_setopt($curl_handleCURLOPT_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
        
}
    }


Bans, delays, throttles

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.
        

A full featured Google scraper powered through our API


A good example on how to use our API for a professional project is provided through the free PHP Search Engine Scraper
Another example is a scraper of Google Suggest/Autocomplete: Google Suggest Scraper