Proxy Detection API

You need to decide in real time whether an incoming IP is using a proxy, and you want a single API call that returns geolocation and a clear security flag you can wire into your risk engine. By the end of this guide, you’ll be able to call the ipXapi Proxy Detection endpoint, parse security.is_proxy reliably, and ship a production-ready check with predictable behavior.

What you’ll get from the Proxy Detection lookup

The Proxy Detection lookup returns geolocation, network ownership, and security signals for a queried IP. The key field for proxy workflows is security.is_proxy, a boolean you can route directly into allow/deny, step-up authentication, or review queues. You’ll also receive additional context such as country, region, city, coordinates, and ISP/AS strings that help with audit logging and analytics.

• Proxy verdict: security.is_proxy
• Additional network signals: security.is_vpn and security.is_cloud_provider
• Geolocation context: country, region, city, lat/lon, timezone
• Attribution strings: isp, org, as

Endpoint, method, and authentication

Endpoint path: /api/ip

HTTP method: GET

Query parameter: ip (the IP address you want to evaluate; the fixture below uses 148.105.12.120)

Authentication: Bearer token in the Authorization header. Use your API key as a bearer token.

• Header: Accept: application/json
• Header: Authorization: Bearer YOUR_API_KEY

If you’re new to the service or need schema details, see the Documentation.

Quick start with cURL

The following is the official, copy-pasteable request using the documented fixture IP and headers.

curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"

Official sample response

Below is the official JSON for the same fixture IP. Live results can change based on data freshness and network shifts, so treat this as a product example rather than the current status of the IP.

{
"status": "success",
"country": "United States",
"countryCode": "US",
"region": "US-CA",
"regionName": "California",
"city": "Mountain View",
"zip": "94043",
"lat": 37.40599,
"lon": -122.0786,
"timezone": "America/Los_Angeles",
"isp": "MailChimp",
"org": "MailChimp",
"as": "AS14782 MailChimp",
"query": "148.105.12.120",
"inEU": false,
"continentCode": "NA",
"security": {
"is_proxy": false,
"is_vpn": false,
"is_cloud_provider": true
}
}

Focus on these fields for decisioning:

• status: String; success indicates a valid lookup payload.
• query: The IP you looked up, useful for logs.
• security.is_proxy: Boolean; your primary proxy decision flag.
• security.is_vpn: Boolean; a supplemental privacy-network signal.
• security.is_cloud_provider: Boolean; helps identify traffic likely from data centers.
• timezone: IANA timezone string, useful if you localize messages or analyze behavior by local time.

Parse the proxy verdict in code (JavaScript)

This example calls the same endpoint and extracts the three security booleans, checking status before use. It uses the documented fixture IP and a Bearer token.

async function checkProxy() {
const url = 'https://ipxapi.com/api/ip?ip=148.105.12.120';
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
// Reasonable timeouts are environment-specific; consider abort signals in production
});

if (!res.ok) {
throw new Error('HTTP error ' + res.status);
}

const data = await res.json();

if (data.status !== 'success') {
throw new Error('Lookup did not return success status');
}

const { security, country, regionName, city, timezone, isp, as: asn } = data;
if (!security || typeof security.is_proxy !== 'boolean') {
throw new Error('security.is_proxy missing or invalid');
}

// Production decisioning example
const isProxy = security.is_proxy;
const isVpn = security.is_vpn === true;
const isCloud = security.is_cloud_provider === true;

// Route logic
if (isProxy) {
// Block, step-up auth, or flag for review
console.log('Proxy detected for IP:', data.query);
} else {
// Proceed, possibly with additional checks
console.log('No proxy detected. Geo:', country, regionName, city, 'TZ:', timezone);
}

// Optional: record network context for analytics
console.log('Network Owner:', isp, 'ASN:', asn, 'Cloud Provider:', isCloud, 'VPN:', isVpn);
}

checkProxy().catch(err => {
console.error('Lookup failed:', err.message);
});

Interpreting security flags and shipping to production

security.is_proxy is the core allow/deny control. If you enforce strict proxy policies, treat true as a hard block or trigger for additional verification. If your workflow tolerates some privacy tooling, combine security.is_proxy with security.is_vpn and security.is_cloud_provider to tune outcomes.

• Strict: if security.is_proxy is true, block or require step-up authentication.
• Balanced: if security.is_proxy is true or security.is_vpn is true, allow only low-risk actions or add risk scoring.
• Contextual: when security.is_cloud_provider is true, scrutinize automated behavior but avoid false positives for legitimate B2B traffic.

Operational tips that will save time:

• Timezone: timezone is an IANA identifier (e.g., America/Los_Angeles). Use it for local-time comparisons and messaging.
• Caching: Cache results per IP briefly where acceptable, but remember that proxy/VPN states can change; treat security flags as dynamic.
• Retries: Network blips happen. On non-2xx HTTP, retry with backoff. On status !== success in the JSON, surface a soft error and bypass strict blocks.
• Logging: Persist query, status, and the three security flags for auditability and model tuning.

Plan, trial, and activation

Basic is $29.99/mo. The trial lets you evaluate for 7 days or 50 requests, whichever comes first. Start with the trial, confirm your integration, then move to Basic for steady workloads.

When you’re ready, create an account and retrieve your API key here: Register.

MCP and environments

If you need to reach the Managed Control Plane endpoint, use MCP. Keep your production calls consistent with the headers shown above and ensure outbound firewall rules allow the host you target.

Quality checks before launch

• Validate status === "success" before reading fields.
• Confirm security.is_proxy is a boolean; guard against absent or malformed security objects.
• Record the query IP in your logs alongside the verdict for traceability.
• Apply minimal caching and recheck high-risk sessions more frequently.

Testing with the documented fixture

Use the provided fixture IP 148.105.12.120 during development to standardize your tests. Your staging scripts should hit /api/ip with that IP and confirm the parser paths and decision logic. In integration tests, assert that your code handles changes in security flags without runtime errors, since live indicators can vary over time.

Common integration patterns

• Login hardening: Call the endpoint at credential submission and step up when security.is_proxy is true.
• Payments: On checkout, combine proxy verdict with device fingerprinting and behavioral data.
• Abuse throttling: For write-heavy endpoints, reduce rate limits for IPs with security.is_cloud_provider true.
• Compliance and geo controls: Use country and region fields to apply regional rules, logging timezone for local compliance audits.

FAQ

How do I authenticate?

Send your key as a Bearer token: Authorization: Bearer YOUR_API_KEY, with Accept: application/json.

What is the primary field for proxy detection?

Use security.is_proxy. It’s a boolean you can wire directly into your allow/deny or step-up logic.

Can I rely on the sample JSON as a constant truth?

No. The sample is a documented fixture for integration. Live datasets evolve, so treat proxy/VPN/cloud flags as dynamic signals.

Which endpoint should I call for proxy detection?

Call /api/ip with the ip query parameter. The examples here use 148.105.12.120 for testing.

Is there a trial?

Yes. The trial is 7 days or 50 requests, whichever comes first. Basic is $29.99/mo when you’re ready to ship.

Ready to implement proxy checks that plug into your auth and risk flows? Create your account to get an API key and start integrating today: Register. For full schema and advanced options, see the Documentation. If you deploy via managed endpoints, the control plane is at MCP.