NAV Navbar
shell python
  • Introduction
  • Authentication
  • API Success/Failure handling
  • Rate-Limiting
  • Account
  • Socks Proxies
  • Errors
  • Introduction

    Welcome to PremSocks.com API documentation. You can use our API to:

    You can view code examples in the dark area to the right.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://premsocks.com/api/v1/socks/list"
      -H "Authorization: Bearer [API_KEY]"
    
    #This request would return list of proxies, available on the website. Keep reading for more.
    
    import requests
    
    headers = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/socks/list', headers=headers)
    
    #This request would return list of proxies, available on the website. Keep reading for more.
    print(response.json())
    
    

    Make sure to replace [API_KEY] with your API key.

    PremSocks uses API keys to allow access to the API. You can get your API key on our website.

    Our systems expects for the API key to be included in all requests sent to our server in a HTTP header that looks like the following:

    Authorization: Bearer [API_KEY]

    API Success/Failure handling

    Successfull response:

    {
        "status": true,
        "data": {
            "somedata": "somedata"
        }
    }
    

    Failed response:

    {
        "status": false,
        "error_message": "Daily limit reached",
        "error_code": 1003
    }
    
    

    To check whether any of operation performed using our API succeeded, you have to check status value. If status is true, everything is ok. If the status is false, you can access error_message field to get description of what went wrong.

    For meaning of error codes, please check Errors section.

    ALWAYS check status field in server response before further processing.

    You can see sample responses on right side.

    Rate-Limiting

    400 API requests every minute are allowed. This value applies to all endpoints (summarized)

    It is more than enough for typical usage. So in most cases, you don't have to worry about rate limits.

    In case you hit rate limit, you will receive 429 HTTP status code. You can track rate-limiting status using information returned by our server in HTTP headers on every API response - X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Limit-Reset

    Account

    Get Account/Package Information

    curl "https://premsocks.com/api/v1/account"
      -H "Authorization: Bearer [API_KEY]"
    
    import requests
    
    hdr = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/account', headers=hdr)
    
    print(response.json())
    
    

    The above command returns JSON structured like this:

    
    {
        "status": true,
        "data": {
            "username": "TheJoe",
            "email": "[email protected]",
            "balance": 45.20,
            "package": {
                "name": "Daily - 200",
                "daily_limit": 200,
                "used": 2,
                "limit_remaining": 198,
                "limit_reached": false,
                "days_left": 17,
                "activated_at": "2017-08-23",
                "expires_at": "2017-07-22"
            }
        }
    }
    
    
    

    This endpoint allows you to get information about your account and active package.

    HTTP Request

    GET https://premsocks.com/api/v1/account

    Server Response

    Check sample response on right side.

    Account:

    Key Description
    username Your username
    email Your email
    balance Your balance in USD

    Package:

    Key Description
    name Name of your package plan
    daily_limit Number of proxies you're allowed to fetch every day
    used Number of proxies you've used today.
    limit_remaining Number of proxies you can still fetch today.
    limit_reached Bool value, indicating whether you've reached your daily limit
    days_left Number of days until package expiration
    activated_at Date of package purchase
    expires_at Date of package expiration

    Behaviour

    The server will return information about your account and the active package. You can use this information to access number of remaining proxies you're allowed to fetch and other general package information such as number of days remaining or whether you've reached your daily limit already.

    Socks Proxies

    Get Proxy List

    curl "https://premsocks.com/api/v1/socks/list"
      -H "Authorization: Bearer [API_KEY]"
    
    import requests
    
    hdr = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/socks/list', headers=hdr)
    
    print(response.json())
    
    

    The above command returns JSON structured like this:

    {
        "status": true,
        "count": 2,
        "data": [
          {
            "id": 6937649,
            "ip": "37.59.*.***",
            "hostname": "***.***.ip-37-59-0.eu",
            "isp": "OVH SAS",
            "country": "FR",
            "city": "Roubaix",
            "state": "Nord-Pas-de-Calais",
            "speed": 2
          },
          {
            "id": 6937962,
            "ip": "85.142.***.**",
            "hostname": "***.***.228.42",
            "isp": "Electrovac Hacht & Huber GmbH",
            "country": "DE",
            "city": "Hamburg",
            "state": "Hamburg",
            "speed": 1
            }
        ]
    }
    
    
    

    This endpoint retrieves a list of all proxies available on the website. The IP and hostnames are masked, just like using regular website. You can use the returned list to fetch particiular proxy/s, using one of the returned ID's.

    You can also use query parameters of URL to perform search on the list to narrow results. You can search by Country, City, State, ISP.

    HTTP Request

    GET https://premsocks.com/api/v1/socks/list

    Query Parameters

    Parameter Required? Description
    country No Country code, to search for. Example: "US" or "DE".
    city No City to to search for. Example: "London"
    state No State to search for Example: "California"
    isp No Internet Service Provider to search for. Example: "UPC Austria"

    You can also join the values of parameters to perform search on multiple items. For example to search for proxies from 2 countries US and DE you have to merge them using comma.

    You can do same with other parameters.

    The search query parameters are optional. If you want to get list of all available proxies, just ignore them.

    The filter parameters must be "full" strings. If you look for "Berlin" city, you can't set "Berl" but instead you must specify full string "Berlin". This applies to all parameters. This will be changed in future.

    Server Response

    The server will return JSON data with list of proxies.
    You can see sample response on right side. What you really need to fetch proxy is its "ID".

    Examples

    Get list of proxies from France

    GET https://premsocks.com/api/v1/socks/list?country=FR

    Get list of proxies from France and Netherlands

    GET https://premsocks.com/api/v1/socks/list?country=FR,NL

    Get list of proxies from Germany in Berlin

    GET https://premsocks.com/api/v1/socks/list?country=DE&city=Berlin

    Get Proxy by ID

    curl "https://premsocks.com/api/v1/socks/6937649"
      -H "Authorization: Bearer [API_KEY]"
    
    import requests
    
    hdr = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/socks/6937649', headers=hdr)
    
    print(response.json())
    
    

    The above command returns JSON structured like this:

    
    {
        "status": true,
        "count": 1,
        "requested_count": 1,
        "data": [
          {
            "id": 6937649,
            "ip": "37.59.0.139",
            "port": 4444,
            "proxy_string": "37.59.0.139:4444",
            "hostname": "ns395155.ip-37-59-0.eu",
            "isp": "OVH SAS",
            "country": "FR",
            "city": "Roubaix",
            "state": "Nord-Pas-de-Calais",
            "speed": 2
            }
        ]
    }
    

    This endpoint fetches specific proxy using it's ID as the argument.

    HTTP Request

    GET https://premsocks.com/api/v1/socks/[PROXY_ID]

    URL Parameters

    Parameter Required? Description
    [PROXY_ID] Yes The ID of the proxy to retrieve. You can get the proxy ID from the list, described in previous section.
    You can also request many proxies at once, by seperating their IDs by comma.

    It is highly recommended to fetch multiple proxies at once, instead of doing seperate requests per proxy.

    Server Response

    The server will return JSON data with information about proxy, and what is most important the IP and PORT to use. You can see sample response on right side.

    Due to the fact that proxy might die and dissapear from list, the server will return "requested_count" and "count" values. The "requested_count" indicated number of proxies you asked for, and "count" means number of proxies that the server successfully fetched.

    Although it's very rare, it's possible that if you for example ask for 10 proxies, the server might return just 9. Take that into consideration.

    Behaviour

    If you have enabled "Display Proxy as IP" in your Premsocks account settings, the API will automatically convert proxy to the right format.

    When you fetch a proxy, it will be automatically deducated from yours package's daily limit. If you fetch same proxy twice within one hour, you will NOT be charged twice.

    Examples

    To fetch single proxy by ID:

    GET https://premsocks.com/api/v1/socks/1

    To fetch 3 proxies by ID:

    GET https://premsocks.com/api/v1/socks/1,2,3

    Get Random Proxy

    curl "https://premsocks.com/api/v1/socks/random"
      -H "Authorization: Bearer [API_KEY]"
    
    import requests
    
    hdr = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/socks/random', headers=hdr)
    
    print(response.json())
    
    

    The above command returns JSON structured like this:

    
    {
        "status": true,
        "count": 1,
        "requested_count": 1,
    
        "data": [
          {
            "id": 6937649,
            "ip": "37.59.0.139",
            "port": 4444,
            "proxy_string": "37.59.0.139:4444",
            "hostname": "ns395155.ip-37-59-0.eu",
            "isp": "OVH SAS",
            "country": "FR",
            "city": "Roubaix",
            "state": "Nord-Pas-de-Calais",
            "speed": 2
            }
        ]
    }
    

    This endpoint allows to quickly fetch a random proxy without fetching and processing entire proxy list.

    HTTP Request

    GET https://premsocks.com/api/v1/socks/random

    URL Parameters

    Parameter Required? Description
    count No The number of random proxies to get. By default it fetches 1 proxy.
    country No Country code to get random proxy from. Example: "US" or "DE".

    Server Response

    The server response is exactly same as when fetching the proxy using it's ID. Take a look at Get Proxy By ID section to see response description.

    Examples

    To fetch 5 random proxies:

    GET https://premsocks.com/api/v1/socks/random?count=5

    To fetch 2 random proxies from Germany:

    GET https://premsocks.com/api/v1/socks/random?count=2&country=DE

    Get Proxy History

    curl "https://premsocks.com/api/v1/socks/history"
      -H "Authorization: Bearer [API_KEY]"
    
    import requests
    
    hdr = {"Authorization": "Bearer [API_KEY]"}
    response = requests.get('https://premsocks.com/api/v1/socks/history', headers=hdr)
    
    print(response.json())
    
    

    The above command returns JSON structured like this:

    
    {
        "status": true,
        "count": 2,
        "data": [
            {
                "ip": "37.59.0.139",
                "port": 19397
            },
            {
                "ip": "35.162.5.84",
                "port": 4444
            }
        ]
    }
    
    

    This endpoint allows to access list of proxies which you have fetched in the past 1 hour.

    HTTP Request

    GET https://premsocks.com/api/v1/socks/history

    Server Response

    The server will return list of proxies which you have fetched in last 1 hour. For each proxy you get IP and PORT.

    We realize that only 1 hour is less than using main website. However such API policy is enforced by our vendor.

    Errors

    Sample failed request with error_code used.

    {
        "status": false,
        "error_message": "No proxy with this id found",
        "error_code": 1000
    }
    
    

    You can expect following HTTP status codes from our API:

    HTTP Status Code Meaning
    401 Unauthenticated or No/Incorrect/expired API key.
    429 Rate-Limits hit
    404 API Endpoint not found
    503 API is down or undergoing maintenance

    Except of HTTP status codes, we also use internal status codes to help you determine what happened when performing certain actions. When something goes wrong, the API will generally return 200 HTTP Status Code but the response will have status key set to False and the error_code will be set to one of following values, depending on module used:

    You can use these codes below to quickly determine what happened:

    Example: If you get error code set to 1003 then you can stop fetching the proxies because your daily limit has been reached.

    Internal Error Code Meaning
    0 Generic error. We're not sure what happened
    401 Unauthenticated. No/Incorrect/expired API key.
    1000 Proxy with this ID not found
    1001 You dont have package or balance to fetch this proxy
    1002 You dont have enough balance to fetch this proxy
    1003 You have reached your daily limit
    1004 The number of ordered proxies exceedes remaining limit