Cloud Provider IP Lookup API

You need to programmatically determine whether an IP address belongs to a cloud provider so you can route traffic, challenge sessions, or tune fraud rules accordingly. By the end of this guide, you’ll be able to query ipXapi’s Cloud Provider IP lookup, parse the security.is_cloud_provider flag, and ship a minimal integration that you can expand in production.

What you’ll build

This guide walks through a direct HTTP call to the ipXapi Cloud Provider IP endpoint, shows how to authenticate with a Bearer token, and parses the security.is_cloud_provider field from the response. You’ll copy a working curl command, read the official sample JSON, and implement a small JavaScript helper you can drop into any server or edge function.

When to check for a cloud provider IP

Cloud-originated traffic can be benign (CI/CD, uptime monitors, integration tests) or sensitive (bot scraping, credential stuffing, or inventory probing). The simplest mitigation path is to add a lookup before your risk decision. With a single boolean, you can add higher-friction flows (step-up auth, rate caps) for cloud IPs without breaking normal users.

Endpoint, auth, and base URLs

ipXapi provides a single lookup path for this workflow:

• HTTP method: GET
• Path: /api/ip
• Query parameter: ip
• Auth header: Authorization: Bearer YOUR_API_KEY

All examples below target the ipXapi base domain. Management and control-plane resources are available at MCP.

Pricing note: the Basic plan is $29.99/mo. A trial is available for 7 days or 50 requests. For plan details beyond these top-line notes, see the Documentation.

Official curl and JSON sample

Use the following official curl exactly as shown. It demonstrates a lookup of a documented fixture IP. Replace the token with your own key when running this against your account.

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

Official product-fixture JSON response for that IP (values may differ in live queries). Do not treat this as your caller’s IP; it is a fixed sample for documentation purposes:

{
"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
}
}

What matters for cloud detection is security.is_cloud_provider. The rest of the fields can support routing or analysis, including timezone (IANA identifier), latitude/longitude (decimal degrees), and high-level network attribution. Live flags can change, so always read values from the response you receive rather than hard-coding assumptions.

Quick-start integration

You can get a baseline integration working with a single function call. The snippet below uses standard fetch; any HTTP client works as long as you pass the Authorization header.

// Minimal JavaScript helper to check if an IP is from a cloud provider
async function isCloudProviderIP(ip) {
const url = `https://ipxapi.com/api/ip?ip=${encodeURIComponent(ip)}`;
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
});

if (!res.ok) {
// Surface the HTTP status so you can add retries or circuit breaking upstream
const text = await res.text().catch(() => '');
throw new Error(`ipXapi lookup failed: ${res.status} ${res.statusText} - ${text}`);
}

const data = await res.json();

// Always guard nested access; fields may be absent on certain responses
const security = data && data.security ? data.security : {};
return Boolean(security.is_cloud_provider);
}

// Example usage with the documented fixture IP
isCloudProviderIP('148.105.12.120')
.then(isCloud => {
if (isCloud) {
console.log('Cloud-origin IP: apply higher-friction or internal routing.');
} else {
console.log('Non-cloud IP: proceed with standard flow.');
}
})
.catch(err => {
console.error('Lookup error:', err);
});

Keep the logic tolerant to transient network failures. Treat non-2xx HTTP responses as soft failures and choose a safe default for your application (for example, log and allow, or log and challenge depending on your risk posture).

Making calls in production

Authentication and header hygiene

Always send Authorization: Bearer YOUR_API_KEY and Accept: application/json. Do not put the API key in query parameters. Store the key in your secret manager and inject it at runtime via environment variables. Avoid logging the key or full headers in production logs.

Choosing when to call

Call the IP lookup as early as possible in your request flow, ideally at your edge or gateway layer where the client IP is still accessible before proxy hops. If you use a CDN or reverse proxy, prefer the trusted client IP from your network’s canonical header and sanitize or ignore untrusted forwarded headers set by clients.

Caching

• IP reputation changes, but not per-request. Cache lookups by IP for a short window that matches your risk tolerance. Many teams start with a 15–60 minute TTL and adjust based on incident review.
• Keep an allowlist/denylist layer for known internal scanners and nightly jobs. Cache those indefinitely and bypass the network call.
• Invalidate cache entries explicitly if your fraud tooling or telemetry detects a shift in behavior for a given IP or subnet.

Timezones and units

• timezone is an IANA identifier. Treat it as a string for display or indexing; do not assume it matches OS locale names.
• lat and lon are decimal degrees. If you map these to tiles, ensure your library expects WGS84 coordinates.

Resiliency patterns

• Implement a short timeout for the lookup so it never dominates your response latency. Integrate with your circuit breaker or retry policy as appropriate.
• Pick a safe default if the service is unreachable. For login flows, some teams prefer to challenge rather than block; for content pages, prefer to allow and monitor.
• Log failures with enough context (IP, request ID, HTTP status) to diagnose without storing sensitive tokens.

Testing your integration

Before hitting production traffic, validate that your pipeline extracts the client IP consistently and that the lookup runs only once per request path. Use the documented fixture IP to confirm your parsing logic for security.is_cloud_provider. Then test with a few known non-cloud residential IPs from your office or mobile hotspot to ensure your branching behavior is correct.

• Unit tests should mock the /api/ip response and assert that your code handles both true and false values for security.is_cloud_provider.
• Integration tests can record a single golden response and compare structural fields (presence of security, booleans) rather than exact values, since live flags can change.
• If you deploy to multiple regions, verify you propagate the Authorization header and do not get blocked by egress rules.

Rollout checklist

• Secret management: API key configured in all environments and rotated on a schedule.
• Edge extraction: correct client IP field chosen for your network topology.
• Timeouts and fallbacks: set timeouts and define a default action on failure.
• Caching: TTL chosen and implemented; cache invalidation tool or command in place.
• Monitoring: log error rates and latencies; add simple dashboards for lookup volumes and error ratios.
• Budget guardrails: with a trial of 7 days or 50 requests and Basic at $29.99/mo, add counters so test loops don’t exhaust quotas accidentally.

Implementation notes that save time

• Single field focus: the only field you need for cloud detection is security.is_cloud_provider. Read this boolean directly and branch; do not infer cloud status from org or ASN names.
• Stable shape, variable values: treat the response schema as stable but the values as dynamic. Your code should not assert on specific country, ISP, or organization values.
• One endpoint: all examples use GET /api/ip with the ip query parameter. Avoid building assumptions about additional endpoints or batch features unless they are documented.
• Idempotent lookups: cache or dedupe concurrent requests for the same IP within a short interval to reduce cost and latency spikes.
• Observability: tag logs with the IP and the boolean decision only. Avoid persisting full JSON unless needed for short-term debugging with proper retention policies.

End-to-end example flow

1. Extract client IP from your ingress layer.
2. Check in-memory or distributed cache for a recent decision for that IP.
3. If not cached, call https://ipxapi.com/api/ip?ip=CLIENT_IP with Authorization: Bearer YOUR_API_KEY and Accept: application/json.
4. Parse JSON and read security.is_cloud_provider. Store the boolean and a short TTL in cache.
5. Branch your logic:
   • true: add step-up auth, stricter rate limits, or route to a low-risk path.
   • false: continue standard flow.
6. Emit metrics on lookups, cache hit ratio, and the rate of cloud vs. non-cloud traffic over time.

Troubleshooting

• 401/403 responses: confirm the Authorization header is present and unmodified by proxies. Ensure you did not accidentally put the key in the URL.
• Unexpected nulls: guard access to nested fields like security in your parser and fall back gracefully.
• High latency: move lookups to the edge and enable caching. Avoid serial lookups when processing batched requests—dedupe by IP per request cycle.
• Discrepancies between environments: verify you’re using the same outward-facing egress IPs and that corporate proxies aren’t rewriting headers.

Frequently asked questions

How do I authenticate requests?
Send Authorization: Bearer YOUR_API_KEY along with Accept: application/json on every call to /api/ip.

Which field tells me if an IP is from a cloud provider?
Read security.is_cloud_provider from the JSON response and treat it as a boolean.

Can I rely on other fields (like ISP or ASN) to infer cloud status?
Do not infer cloud status from other fields. Use security.is_cloud_provider directly.

Do response values change over time?
Yes, live flags and attributes can change. Cache conservatively and always read values from the latest response.

Is there a way to try the API before paying?
A trial is available for 7 days or 50 requests. When you’re ready to continue, the Basic plan is $29.99/mo. For details, see the Documentation.

Where to go next

Register for an API key and wire this lookup into your gateway, auth service, or bot mitigation flow. Start with a short TTL cache, add metrics on security.is_cloud_provider rates, and iterate based on real traffic. Create your account here: Register. For reference and additional details, see the Documentation and keep an eye on MCP.