Privacy Detection API

You need to detect whether an incoming IP is using a proxy or VPN, see its basic geolocation, and decide whether to allow, challenge, or block a request—all in a single call. By the end of this guide you will be able to query the Privacy Detection endpoint, interpret the security flags, and wire the response into your auth, payments, or abuse-prevention flows.

What you can look up with the Privacy Detection endpoint

The Privacy Detection lookup helps you answer five operational questions in real time:

• IP geolocation: country, region, city, ZIP, latitude/longitude, timezone.
• Proxy detection: whether the IP is flagged as a proxy.
• VPN detection: whether the IP is flagged as a VPN exit.
• ASN/ISP: high-level network ownership descriptors via isp, org, and as.
• IP reputation signals: the security object provides the privacy-related booleans you can enforce on.

Everything you need is provided by a single GET to the path /api/ip with an Authorization: Bearer header.

Endpoint, authentication, and environments

The Privacy Detection lookup uses the path /api/ip and accepts the target IP as a query parameter. Authentication is via an Authorization: Bearer token. Use your API key server-side and keep it out of client bundles.

• Base: https://ipxapi.com
• Path: /api/ip
• Auth: Authorization: Bearer YOUR_API_KEY
• Management/control plane: MCP
• Docs: Documentation

Trial details: 7 days or 50 requests, whichever comes first. Basic plan is $29.99/mo. You can create an account at Register.

Make your first request

Below is a copy-pasteable cURL against the documented fixture IP. It uses Bearer auth and requests JSON.

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

Notes:

• The ip query parameter specifies the address you want to check. For testing, use the provided fixture value 148.105.12.120.
• In your production code, replace the Authorization value with your actual key. Keep keys out of client code and logs.

Official JSON response and how to read it

Here is the official sample JSON for the fixture IP. Live flags can change; do not treat this as your current 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
}
}

Field highlights you will actually use:

• security.is_proxy: boolean. True if the IP is detected as a proxy.
• security.is_vpn: boolean. True if the IP is detected as a VPN exit.
• security.is_cloud_provider: boolean. True if the IP is attributed to a cloud provider range.
• country, region, regionName, city, zip: coarse geolocation for policy and UX.
• lat, lon: numeric degrees for coordinate-aware routing or rough distance checks.
• timezone: IANA zone string (e.g., America/Los_Angeles) for consistent timestamp formatting.
• isp, org, as: network descriptors (including ASN text) for allow/block logic or analytics.
• query: echoes the looked-up IP.

Minimal JavaScript integration

This example queries the same endpoint and branches on the security flags. It uses the documented path and reads only fields shown in the official sample. Replace YOUR_API_KEY with your real key in a secure server-side context.

async function checkIpPrivacy(ip) {
const url = `https://ipxapi.com/api/ip?ip=${encodeURIComponent(ip)}`;
const res = await fetch(url, {
headers: {
Accept: "application/json",
Authorization: "Bearer YOUR_API_KEY"
}
});

if (!res.ok) {
// Avoid leaking internals; log server-side
const text = await res.text();
throw new Error(`ipxapi lookup failed: ${res.status} ${text}`);
}

const data = await res.json();

// Expected keys per official sample
const security = data.security || {};
const isProxy = security.is_proxy === true;
const isVpn = security.is_vpn === true;
const isCloud = security.is_cloud_provider === true;

// Example policy: challenge VPN/proxy, allow residential
let action = "allow";
if (isProxy || isVpn) {
action = "challenge";
} else if (isCloud) {
// tighten rules for cloud origins (often non-user traffic)
action = "review";
}

return {
action,
country: data.country,
region: data.region,
city: data.city,
timezone: data.timezone,
isp: data.isp,
asnText: data.as,
query: data.query,
security: { isProxy, isVpn, isCloud }
};
}

// Example usage with the documented fixture IP
checkIpPrivacy("148.105.12.120")
.then(console.log)
.catch(console.error);

Interpreting proxy, VPN, and cloud flags in workflows

The three booleans under security give you immediate policy levers without maintaining your own IP lists:

• If security.is_proxy is true: enforce higher-friction checks (2FA, CAPTCHA) or deny sensitive actions like card updates.
• If security.is_vpn is true: allow read-only browsing but gate account creation or high-value transactions.
• If security.is_cloud_provider is true: treat as potential bot or server-to-server source; throttle or require signed requests.

Combine these signals with geolocation (country, timezone) and ASN text (as) to fit your risk profile. Keep the logic straightforward and auditable.

Data handling, caching, and performance tips

• TTL and volatility: IP-to-entity mappings and privacy flags can change. Cache responses for a short window aligned to your risk tolerance. For auth flows, consider a cache of minutes; for analytics, hours may be acceptable.
• Coordinate units: lat and lon are decimal degrees. Use standard great-circle formulas if you compute distances.
• Timezone: timezone is IANA format (e.g., America/Los_Angeles). Use this to render times consistently in emails and UI.
• Normalization: store normalized booleans for is_proxy, is_vpn, is_cloud_provider and keep the raw JSON for audits.
• Error strategy: always handle non-2xx responses. Fall back to a safe default (e.g., challenge) if the lookup fails in a sensitive path.
• Server-side calls: perform lookups from your server. Avoid exposing the Bearer key in client code or public repos.

Testing with the documented fixture IP

Use 148.105.12.120 with the same path for development and automated tests. Write assertions only against field presence and types, not specific live values, because live flags can change. For example, test that security has boolean keys is_proxy, is_vpn, and is_cloud_provider, and that country is a string.

Building allow/challenge/deny rules

Step 1: Gather signals

On request entry, capture the apparent client IP from your edge or load balancer. If you are behind a proxy, read the standardized header your platform sets and avoid trusting unvalidated X-Forwarded-For chains.

Step 2: Query the endpoint

Call /api/ip with the captured IP and your Bearer token. Timebox the call with a short timeout, and proceed with a conservative default on failure.

Step 3: Decide and act

Use the security flags to pick an action. Persist the result along with request identifiers so you can analyze outcomes and tune thresholds later. For example, allow if all three flags are false, challenge if is_proxy or is_vpn is true, and review if is_cloud_provider is true.

Operational considerations

• Idempotency: lookups are read-only; you can repeat calls safely if a retry occurs.
• Batched traffic: for batch jobs, rate-limit your own callers and add lightweight caching keyed by IP.
• Auditing: log the query IP, status, and the three security booleans. Avoid logging PII beyond what is essential.
• Regionalization: use country and region fields for region-aware content and compliance routing.

Security notes

• Key management: store YOUR_API_KEY in your server’s secret manager; never hardcode it in source control.
• Input validation: ensure the ip parameter is a valid IPv4/IPv6 literal before calling the API. Disallow private/reserved ranges when appropriate for your workflow.
• Abuse resilience: do not block solely on one signal. Combine the three security booleans with device, session, or velocity checks.

Troubleshooting

• Unexpected geolocation: IP-to-location is approximate and can reflect network PoPs. Use it for policy, not precise user positioning.
• Changing flags: IP reputation evolves. If your tests depend on a specific value, stub responses in unit tests rather than asserting on live flags.
• Handling timezones: use the returned IANA timezone to render timestamps in notifications; do not assume country equals local time.

Pricing and trial

The Basic plan is $29.99 per month. A trial is available for 7 days or 50 requests (whichever comes first). Start by creating an account: Register. Review capabilities and examples in the Documentation. You can also access the management plane at MCP.

FAQ

Which fields indicate privacy tooling?
Use the booleans under security: is_proxy, is_vpn, and is_cloud_provider.

Can I cache results?
Yes. Cache by IP with a short TTL that matches your risk tolerance. Re-query for high-value actions.

What timezone format is returned?
timezone is an IANA identifier such as America/Los_Angeles.

Do I need to pass any headers besides Authorization?
Send Accept: application/json. The Authorization header uses the Bearer scheme with your API key.

Is the fixture IP my current IP?
No. It is provided for testing only. Live flags can change and do not reflect your current network.

Ship your integration now: create an account at Register, review the Documentation, and manage keys and settings in MCP. Implement a single call to /api/ip and wire the security flags into your allow, challenge, and deny paths.