Introduction

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

• Search our proxy list
• Fetch one or more proxy
• Get account information
• Get package information (remaining limits etc.) tied to your account.

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

Successful server response:

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

Failed server 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.

The exception is /api/v1/list endpoint which has limit of 10 requests per minute

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:

Package:

Behavior

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, 
        "version": 5
      },
      {
        "id": 6937962,
        "ip": "85.142.***.**",
        "hostname": "***.***.228.42",
        "isp": "Electrovac Hacht & Huber GmbH",
        "country": "DE",
        "city": "Hamburg",
        "state": "Hamburg",
        "speed": 1,
        "version": 5
        }
    ]
}

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 particular 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, Speed.

HTTP Request

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

Query Parameters

You can also join the values of parameters to perform search on multiple items. For example to search for proxies from 2 countries FR 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 France with fast speed

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

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,
        "version": 5
        }
    ]
}

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

It is highly recommended to fetch multiple proxies at once, instead of doing separate 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, as well as detailed description below.

Due to the fact that proxy might die and disappear 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.

Proxy:

Behavior

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 deducted 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,
        "version": 5
        }
    ]
}

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

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

To fetch 2 random proxies from Germany with fast speed:

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

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,
            "version": 5
        },
        {
            "ip": "35.162.5.84",
            "port": 4444,
            "version": 5
        }
    ]
}

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 2 hours. For each proxy you get IP and PORT.

We realize that only 2 hours is less than using main website. However such API policy is enforced by our proxy supplier.

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:

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:

• 1000 - proxy module

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.