Good-Proxies.ru
Home

API Documentation for Retrieving Proxies

Description

This API provides access to a list of proxy servers with customizable filters. Working with the API requires a valid access key, which is verified for authenticity and compliance with usage limits. In response to a request, the user receives data depending on the get parameter in the form of text, JSON, or a downloadable file. The API is available at https://api.good-proxies.ru/api.

Main Request Parameters

Parameter Description Required Example Value
key Access key required for request authentication. Yes abc123
type Type of proxy servers (http, https, socks4, socks5). Multiple types can be specified separated by commas. No http,https
anon Proxy anonymity level (transparent, anonymous, elite). No elite
ping Maximum allowed proxy response time in milliseconds. No 500
time Maximum time (in seconds) since the last proxy check. Default: 600 (last 10 minutes). No 600
works Percentage of successful proxy tests out of total attempts. Available values: from 0 to 100. Example usage: works=50 - this means that proxies with at least 50% successful checks out of the total number of tests will be returned. The value is displayed if the json format is selected. No 50
country Proxy country code (ISO Alpha-2). Multiple codes can be specified separated by commas. No us,ca
cm / country_mode Country filter mode. Value include (default) - return only the specified countries. Value except - exclude the specified countries from results. A short parameter cm (e.g. cm=except) is supported and is compatible with the legacy country_mode. No cm=except & country=us,ca
city Proxy city name. Multiple cities can be specified separated by commas. Names can be in Russian or English. No Paris,Moscow
count Number of proxies requested. No 10
lang Language for city names in the response and when filtering by city. ru (default) - Russian city names. en - English city names. With lang=en the city parameter accepts English city names. No ru, en
get Data output format. By default, txt is used, which means output as text in the browser. For JSON format output use get=json. To download a file use get=txt.file or get=json.file. No txt, json, txt.file, json.file
timecheck Time of the last successful proxy functionality check. Displayed only if json format is selected. Time is indicated in GMT+2 timezone. No Cannot be specified
ip_out Outgoing resulting proxy IP address. May differ from the main proxy IP address. This parameter is displayed only in JSON format. No Cannot be specified

TXT Format Parameters

The following parameter controls the line format for get=txt and get=txt.file.

Parameter Description Required Example Value
type_prefix Adds the protocol prefix to each TXT output line: type://ip:port. Value 1 enables the mode. Example line: http://127.0.0.1:3128. No 1

JSON Format Parameters

The following parameters control the response structure for get=json and get=json.file. They do not affect TXT output.

Parameter Description Required Example Value
ip Proxy server address in ip:port format (e.g. 192.168.1.1:8080). To split into separate ip and port fields, use the split_ip=1 parameter. No 192.168.1.1:8080
fields Comma-separated list of fields to include in the JSON response. Allowed: ip, port, ip_out, type, anon, ping, timecheck, country, city, works. By default all fields are returned. The port field only appears with split_ip=1. No ip,type,country
split_ip Splits the ip field in ip:port format into two separate fields: ip and port. Value 1 enables splitting. No 1
format JSON response structure. array (default) - array of proxy objects. object - object where keys are proxy addresses (ip:port) and values are field objects. No array, object
wrap Wraps the response in a metadata envelope: {status, count, timestamp, filters, data}. Value 1 enables wrapping. No 1
pretty JSON response formatting. 1 (default) - human-readable format with indentation. 0 - compact JSON without indentation (less traffic). No 0, 1

Request Examples

Example 1: 5 proxies with HTTP type and "elite" anonymity in JSON format

GET https://api.good-proxies.ru/api?key=abc123&type=http&anon=elite&count=5&get=json

Example 2: 10 proxies with HTTPS type and maximum ping 500 ms in TXT file format for download

GET https://api.good-proxies.ru/api?key=abc123&type=https&ping=500&count=10&get=txt.file

Example 3: 2 proxies from USA and Canada in list format (displayed as text in browser)

GET https://api.good-proxies.ru/api?key=abc123&country=us,ca&count=2

Example 4: TXT with protocol prefix type://ip:port

GET https://api.good-proxies.ru/api?key=abc123&type=http&count=5&type_prefix=1

Output:

http://192.168.1.1:8080
http://192.168.1.2:3128
http://192.168.1.3:8118

Example 5: JSON - selected fields only, IP and port split

GET https://api.good-proxies.ru/api?key=abc123&type=socks5&count=2&get=json&fields=ip,port,type,country&split_ip=1

Output:

[
    {
        "ip": "192.168.1.1",
        "port": "1080",
        "type": "socks5",
        "country": "US"
    },
    {
        "ip": "192.168.1.2",
        "port": "1080",
        "type": "socks5",
        "country": "DE"
    }
]

Example 6: JSON with metadata envelope (wrap=1)

GET https://api.good-proxies.ru/api?key=abc123&type=http&count=2&get=json&wrap=1

Output:

{
    "status": "ok",
    "count": 2,
    "timestamp": "2026-03-01T12:00:00+00:00",
    "filters": {
        "type": "http",
        "time": 600
    },
    "data": [
        {
            "ip": "192.168.1.1:8080",
            "type": "http",
            ...
        }
    ]
}

Example 7: Filter by city in English

GET https://api.good-proxies.ru/api?key=abc123&city=Paris,London&count=5&get=json&lang=en

The lang=en parameter allows specifying cities in English and receiving English city names in the response.

Example 8: Compact JSON without indentation (for automated processing)

GET https://api.good-proxies.ru/api?key=abc123&type=http&count=10&get=json&pretty=0

Response Format

Successful JSON Response

Upon a successful request with the get=json parameter, the API returns a list of proxy servers in structured JSON format. Includes the timecheck parameter, which shows the time of the last successful check in GMT+2 timezone. The ip_out parameter indicates the resulting proxy IP address, which may differ from the main one.

[
    {
        "ip": "15.162.126.1:919",
        "ip_out": "15.162.126.1",
        "type": "http",
        "anon": "transparent",
        "ping": 5.07786,
        "timecheck": "2024-11-25 20:09:25",
        "country": "CO",
        "city": "Медельин",
        "works": "66"
    }
]

Successful TXT Response

If the parameter get=txt (default), data is returned as a plain text file displayed in the browser:

192.168.1.1:8080
192.168.1.2:8080
192.168.1.3:8080

Successful TXT Response for Download

If the parameter get=txt.file, data will be offered for download in text format:

192.168.1.1:8080
192.168.1.2:8080
192.168.1.3:8080

Successful JSON Response for Download

If the parameter get=json.file, data will be offered for download in JSON format:

[
    {
        "ip": "112.63.11.8:180",
        "ip_out": "122.63.41.1",
        "type": "http",
        "anon": "elite",
        "ping": 3.83659,
        "timecheck": "2024-11-25 20:09:26",
        "country": "SN",
        "city": "",
        "works": "100"
    }
]

Errors

If the request fails, the API returns a text message describing the error.

Error: Access key not provided

Limits

  • Request frequency: no more than two requests every 5 seconds.
  • Daily request limit: up to 34,560 requests. When the limit is exceeded, the API returns an error message.
  • Subnet restriction: no more than 10 IP subnets in "a.b.0.0/16" format. The limit resets every 24 hours. If the limit is exceeded, the API returns an error.

Notes

  • All parameters except key are optional.
  • If the count parameter is not specified, the API returns the maximum number of available proxies.
  • If the time parameter is not specified, the default value 600 is used (proxies checked within the last 10 minutes).
  • When using the parameter get=txt.file or get=json.file, data will be offered for download as a file.
  • The time in the timecheck field, returned in JSON format, is specified in GMT+2 timezone.
  • JSON parameters (fields, split_ip, format, wrap, pretty) only affect JSON responses and are ignored for TXT output.
  • The type_prefix parameter only affects TXT output (get=txt and get=txt.file) and is ignored for JSON output.
  • The lang=en parameter allows specifying city names in the city filter in English and returns them in English in the JSON response.

PHP Usage Example

$key = 'abc123';
$type = 'http';
$anon = 'elite';
$count = 5;
$get = 'json';

$url = "https://api.good-proxies.ru/api?key=$key&type=$type&anon=$anon&count=$count&get=$get";

$response = file_get_contents($url);

if ($response) {
    $proxies = json_decode($response, true);
    print_r($proxies);
} else {
    echo "Error retrieving proxies.";
}

Conclusion

The API provides a convenient tool for retrieving proxy servers with extensive filtering capabilities. Make sure you have a valid access key and observe the limits for uninterrupted service operation.