API REFERENCE / v1

Proxy detection
API documentation.

Check one public IPv4 or IPv6 address per request. ProxyRadar returns an overall proxy classification and available network flags for VPN, hosting, Tor, public proxies and known crawler networks.

Make your first request

Create a free account and copy your API key from the dashboard. Prefer the Authorization header so your key stays out of URLs. Keep the key on your server.

curl --get 'https://proxyradar.io/v1/check' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'ip=185.220.101.44' \
  --data-urlencode 'format=json'

Read the JSON response

This example illustrates the response structure; it is not a permanent verdict for the example address. Successful JSON responses include the available location, ASN and risk context automatically.

{
  "status": "success",
  "ip": "8.8.8.8",
  "proxy": 1,
  "flags": {
    "vpn": false,
    "hosting": true,
    "tor": false,
    "public_proxy": false,
    "known_bot": false
  },
  "enrichment": {
    "version": "1",
    "location": {
      "status": "available",
      "country_code": "US",
      "country": "United States",
      "continent_code": "NA",
      "continent": "North America",
      "region": "California",
      "city": "Mountain View",
      "latitude": 37.422,
      "longitude": -122.085,
      "approximate": true
    },
    "network": {
      "status": "available",
      "asn": 15169,
      "organization": "GOOGLE"
    },
    "risk": {
      "status": "available",
      "score": 30,
      "level": "elevated",
      "reasons": [
        {
          "code": "hosting",
          "weight": 30,
          "description": "Hosting network identified; this alone is not abuse."
        }
      ],
      "category_coverage": "available"
    }
  }
}

Category values can be true, false or null. True identifies a category match; false means that category was not identified; null means category information was unavailable. An overall positive result can have no true category flags. Always use proxy for the overall classification.

IP location, ASN and risk context

Every successful JSON response includes an enrichment object with available location, ASN and risk information. No extra parameter is required. The endpoint, API key, proxy classification and account limits stay the same. The complete lookup uses one query, with no extra query charge.

curl --get 'https://proxyradar.io/v1/check' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'ip=8.8.8.8' \
  --data-urlencode 'format=json'

Existing requests that send enrich=1 still work with the same enrichment structure. Plain Y/N responses remain unchanged. Location and ASN are also available in the account IP checker.

Location and network have their own status: available, partial, not_found or unavailable. A missing or stale enrichment file never changes a successful proxy answer. When classification itself fails, the usual error response applies and no score is returned.

Transparent scoring rules

The network-exposure-v1 model uses the strongest applicable weight below; overlapping labels are not added together. Weights are explicit product policy choices, not statistically calibrated probabilities. Country, city, coordinates and ASN identity do not increase the score. No decision automatically blocks a visitor.

For a negative result with any missing VPN, hosting, Tor or public-proxy category, risk.score is null, risk.level is unknown and risk.status is insufficient_data. A positive signal can still produce a score with category_coverage: partial; inspect that field before using thresholds. Known crawler networks do not lower the score or establish that a request is trustworthy. A score of 85 does not mean an 85% chance of abuse. Even the baseline of 10 is not a measured fraud rate.

Risk contains status, score, level, reasons (code, weight, description) and category_coverage. Use your own account and request behavior before taking action.

Data freshness and attribution

Location lookups use a local copy of DB-IP City Lite. The updater checks daily for its monthly release. Stale or damaged data becomes unavailable; checking for updates does not change the publication date. ASN data is refreshed daily from IPtoASN. Neither lookup sends the requested address to these data publishers.

IP Geolocation by DB-IP, CC BY 4.0. Credit DB-IP when using the data; include a link to DB-IP on web pages displaying or using its results. Fields are selected and normalized from DB-IP City Lite. IPtoASN network data uses PDDL. Source credits are documented here and in the third-party notices; the JSON response links here through its Link HTTP header.

Account lists and custom rules

Use the Lists & rules workspace to create allowlists, blocklists and custom groups. Entries can be individual IPv4/IPv6 addresses, CIDRs, start–end ranges or AS numbers. Paste one entry per line. Every account can keep 20 active lists, up to 1,000 entries each and 5,000 stored entries in total, and 30 active rules.

Existing API requests keep their detection result. To evaluate your account policy, request JSON and add policy=1:

curl --get 'https://proxyradar.io/v1/check' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-urlencode 'ip=8.8.8.8' \
  --data-urlencode 'format=json' \
  --data-urlencode 'policy=1'

Only this opt-in adds a policy object. The original proxy, category flags, location, ASN and risk score remain detection evidence; a customer policy never rewrites them. Plain Y/N ignores the policy parameter. The complete lookup still consumes one query.

"policy": {
  "status": "matched",
  "action": "review",
  "matched": {"type": "rule", "id": "YOUR_RULE_ID", "name": "Review higher network risk"}
}

Order: enabled allowlist matches, enabled blocklist matches, then enabled rules in ascending priority order. Ties use the stable rule ID in ascending order. The first matching rule wins. A custom group only acts when a rule references it. If an earlier decision needs unknown data, evaluation stops with unavailable / review; a negative condition does not turn unknown into true.

Rules combine one to four conditions with ALL (AND) or ANY (OR). Available conditions: list membership, IP/range, ASN, country code, risk threshold, overall proxy result, VPN, hosting, Tor, public proxy and known crawler. ASN and country accept comma-separated values. A disabled or archived referenced list is unknown. Re-enabling that list makes it available to its rules again.

New items start disabled. Use the real-IP preview to test your enabled policy or temporarily include one saved draft without activating it. Each preview uses one normal query. Archive and restore preserve settings; restored items remain disabled. The workspace records recent changes and exports settings as JSON. The dashboard also offers recorded daily usage as CSV for up to 90 days.

Use the compact Y/N format

The original endpoint and query-string key remain supported:

https://proxyradar.io/v1/check?key=YOUR_API_KEY&ip=185.220.101.44

Without format=json, successful lookups return Y for a positive classification and N for a negative classification. Invalid addresses or unavailable detection return X with an error status. Authentication and quota failures use a JSON error. Read the HTTP status as well as the body.

Handle errors and usage limits

Daily quotas reset at 00:00 UTC. Successful responses include X-Daily-Limit and X-Daily-Remaining. The burst limit is 1,200 requests per minute per API key. Each successful lookup consumes one query; failed classifications consume none. A client timeout can occur after a request succeeds on the server, so a retry may count as another successful lookup.

Allow more than 8 seconds in your client timeout; the examples use 15 seconds. Set your application’s unknown-result policy separately from a negative classification. See pricing for current daily allowances.

Use your language

Prefer a ready-to-configure package? Browse WordPress, Cloudflare Workers, Node.js and bulk CSV integrations. They use the same endpoint, account key and quota described here.

Follow the complete Python, Node.js and PHP examples, or download the OpenAPI specification for the endpoint, authentication options and response schema. The browser proxy checker is also available for individual lookups.

Use the result in context

Hosting, VPN and Tor can have legitimate uses. A negative result is not proof of a human or residential connection. Combine network classification with the action being attempted and your own account signals. The coverage reference explains the category limits, and the traffic policy guide shows how to apply them.