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:
Key | Description |
---|---|
username | Your username |
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 |
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
Parameter | Required? | Description |
---|---|---|
country | No | Country code, to search for. Example: "FR" or "DE". |
city | No | City to to search for. Example: "London" |
state | No | State to search for Example: "Bern" |
isp | No | Internet Service Provider to search for. Example: "UPC Austria" |
speed | No | Proxy speed to search for. 1 - Fast, 2 - Medium, 3 - Slow. |
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
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 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:
Key | Description |
---|---|
id | Proxy ID |
ip | Proxy IP address where you should connect |
port | Proxy port where you should connect. |
proxy_string | Combination of ip and port with ':' as delimiter for direct usage in curl. |
version | Version of SOCKS protocol this proxy supports as numeric value. 5 - SOCKS5, 4 - SOCKS4 |
hostname | Hostname of proxy |
isp | Internet Service Provider hosting the proxy |
country | Country code where proxy is located in 2 letter format |
city | City where proxy is located |
state | State where proxy is located |
speed | Speed of proxy as numeric value. 1 - Fast, 2 - Medium, 3 - Slow. |
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
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: "FR" or "DE". |
speed | No | Filter proxy by speed. 1 - Fast, 2 - Medium, 3 - Slow. |
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:
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:
- 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.
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 |