Geolocation IP API

You need to determine a visitor’s country, region, city, and ISP from an IPv4 address, while also checking whether it’s from a VPN, proxy, or cloud provider. By the end of this guide, you will call a geolocation endpoint, parse the JSON, and use the fields that matter for content gating, personalization, and basic fraud controls.

What you get from a single IP lookup

The Geolocation IP endpoint returns location attributes (country, region, city, coordinates, timezone), network data (ISP, organization, AS string), and security flags for proxy, VPN, and cloud provider detection. A single call gives you the minimal set of signals most applications need to localize experiences and filter higher-risk traffic without involving device fingerprinting or cookies.

• Location: country, region and regionName, city, zip, lat/lon, timezone
• Network: isp, org, as (autonomous system string)
• Security: booleans for is_proxy, is_vpn, is_cloud_provider
• Meta: status and query (the IP echoed back)

Live flags can change, so treat security booleans and network metadata as dynamic, not static configuration. Do not treat the documented fixture below as your user’s IP; it’s for testing and documentation only.

Endpoint and authentication

Endpoint path: /api/ip. Pass the target IPv4 address via the ip query parameter. Authentication uses a Bearer token in the Authorization header. Responses are JSON with standard UTF-8 encoding.

• Base URL: https://ipxapi.com
• Path: /api/ip
• Query parameter: ip
• Auth header: Authorization: Bearer YOUR_API_KEY
• Accept header: application/json

You can explore additional details and field semantics in the official Documentation. Management Control Plane access is available at MCP.

Quickstart: curl and JSON fixture

The following request and response are the official, documented example for the fixture IP 148.105.12.120. Copy and run the curl to validate your connectivity and headers. Do not treat these flags as canonical for any live IP; real-time values can change.

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

{
"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 typically use:

• country, countryCode: efficient for geo-based routing and compliance gating
• region, regionName, city, zip: finer-grained localization and marketing attribution
• lat, lon: map rendering and distance calculations (decimal degrees)
• timezone: UI defaults for scheduling, timestamps, and cron-like tasks
• isp, org, as: heuristics for business-vs-residential and traffic analysis
• security.is_proxy, security.is_vpn, security.is_cloud_provider: coarse-grained risk filters

Minimal integration: JavaScript fetch example

This sample calls the same /api/ip endpoint and extracts the fields you are most likely to need in production. Replace YOUR_API_KEY with your token. The example uses the documented fixture IP for demonstration.

// Geolocation lookup with proxy/VPN flags
async function geolocateIp(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) {
// Non-2xx: log and surface a safe fallback
const text = await res.text().catch(() => "");
throw new Error(`ipxapi request failed: ${res.status} ${res.statusText} ${text}`);
}

const data = await res.json();

// Defensive parsing: only read fields you actually use downstream
const result = {
ip: data.query,
country: data.country,
countryCode: data.countryCode,
region: data.region,
regionName: data.regionName,
city: data.city,
zip: data.zip,
lat: data.lat,
lon: data.lon,
timezone: data.timezone,
isp: data.isp,
org: data.org,
as: data.as,
security: {
is_proxy: data.security?.is_proxy === true,
is_vpn: data.security?.is_vpn === true,
is_cloud_provider: data.security?.is_cloud_provider === true
}
};

return result;
}

// Example usage with the documented fixture IP.
// Do not treat fixture values as live reputation or location for your users.
geolocateIp("148.105.12.120")
.then(info => {
console.log("Country:", info.country, info.countryCode);
console.log("Region:", info.region, info.regionName);
console.log("City/ZIP:", info.city, info.zip);
console.log("Coordinates:", info.lat, info.lon);
console.log("Timezone:", info.timezone);
console.log("Network:", info.isp, info.org, info.as);
console.log("Security:", info.security);
})
.catch(err => {
console.error(err);
});

Designing your geolocation flow

Start by calling /api/ip at the earliest point you have an IP address available (often at edge middleware or right after your load balancer). Use the resulting fields to set request-scoped attributes so downstream services can make decisions without repeating the lookup.

Request-time usage

• Country and region gating: assign a countryCode allow/deny rule as early as possible
• Time-bound features: use timezone for default scheduling and date formatting
• Risk controls: if security.is_vpn or security.is_proxy is true, step up verification
• Network heuristics: if as or org suggests hosting, route to read-only flows or throttle

Persistence and privacy

• Cache the full response for a short TTL to reduce latency and cost (for example, a few minutes)
• Store only the minimal subset you need (e.g., countryCode and security flags)
• Avoid treating IP as stable identity; addresses can be shared or rotate

Handling variability and caching

Geolocation and security flags are not static. ISPs reassign blocks, enterprise networks change routing, and proxy/VPN signals can shift. Keep your cache TTL modest and revalidate periodically on important sessions. If the same user’s IP flips subnets or AS during a session, re-fetch rather than relying on stale data.

• Cache key: the remote IP string
• Cache value: parsed JSON fields you actively use
• Invalidation: clear on sign-in, checkout, or other high-risk transitions
• Fallbacks: if lookup fails, default to conservative flows and avoid hard-blocks based solely on errors

Interpreting common fields

Use country and countryCode for high-confidence routing. Region/regionName and city are useful for personalization and analytics but should not alone drive compliance decisions. lat and lon are decimal degrees; use them to compute distances or for map pins, not for precise street-level positioning. timezone strings are IANA identifiers; use them to render local times predictably.

For network attributes, isp and org often match but can differ for resellers; the as string identifies the autonomous system and typically includes a numeric ID and a label. Security booleans are coarse controls. If any flag is true, treat traffic as higher risk and require additional checks (email verification, step-up auth, or lower rate limits) rather than blocking outright unless your policy demands it.

Error handling and resilience

Expect non-200 responses if the IP is malformed, missing, or rate-limited. Treat HTTP failures as soft errors: log them, degrade gracefully, and continue with neutral defaults. Parse the JSON only after a successful status; for failure cases, capture response text for diagnostics and avoid assumptions about schema. Because live flags can change, avoid persisting negative results (e.g., not a VPN) for long durations.

Testing with the documented fixture

Use the provided fixture IP 148.105.12.120 to verify headers, JSON parsing, and your field mappings. This ensures your integration reads country, timezone, and security fields exactly as returned. Once your pipeline works with the fixture, switch to targeting the real client IPs captured by your application or edge.

Pricing, trial, and rollout strategy

The Basic plan is $29.99/mo. You can evaluate via a trial that is 7 days or 50 requests, whichever comes first. Start with the fixture to validate your code path, then allocate a small subset of production traffic to live lookups while you tune caching and thresholds. When in doubt, prefer short TTLs and minimal persistence.

When you are ready, create your API key and begin integration: Register.

Operational notes

• Headers: always send Accept: application/json and Authorization: Bearer YOUR_API_KEY
• Timeouts: use pragmatic HTTP timeouts so your UI is not blocked by network stalls
• Idempotency: GET calls are read-only; you can safely retry on transient failures
• Observability: log the ip parameter, status, and a hash of the response to aid debugging
• Security: do not expose your API key in client-side code; call the API from a trusted server or edge function

FAQ

Does the IP response include VPN or proxy detection?
Yes. Check security.is_vpn, security.is_proxy, and security.is_cloud_provider. Use these booleans as coarse risk signals.

Which parameter selects the IP to look up?
Pass the ip query parameter to /api/ip, for example /api/ip?ip=148.105.12.120.

What timezone format is returned?
The timezone field is an IANA identifier (for example, America/Los_Angeles). Use it directly with libraries that accept TZ database names.

How should I cache results?
Cache by IP with a short TTL. Re-fetch on high-risk actions or if the user’s network characteristics (AS, org, or subnet) change.

Where can I manage access and learn more?
Use the MCP for control-plane access and review the Documentation for field definitions and integration details.

Start your integration with a trial and move to production when your cache and risk rules are tuned. Create your key and begin calling /api/ip today: Register.