IP Address Location API

You need reliable IP geolocation with proxy/VPN detection to personalize experiences, comply with regional policies, or filter risky traffic. By the end of this guide you will be able to call the IP Address Location API, parse its JSON, and use country, region, city, timezone, ISP/ASN, and security flags to make practical decisions in your application.

What the IP Address Location API returns and why it matters

The IP Address Location API provides geolocation data (country, region, city, latitude/longitude, timezone) plus network attributes (ISP, organization, ASN) and security indicators (proxy, VPN, cloud provider). With a single request you can:

• Geolocate an IP to country, region, and city for localization and regional routing.
• Map a request to a timezone for scheduling, timestamps, and logs.
• Use security flags like is_proxy and is_vpn to evaluate request trust.
• Inspect ISP/org/ASN to tune allow/deny logic or analytics.

This post stays focused on geolocation and related detection (proxy, VPN, ASN). All examples use the documented path and fixture IP so you can copy and adapt with minimal changes.

Endpoint, method, and authentication

The IP Address Location API endpoint is a simple HTTP GET that accepts an ip query parameter.

• HTTP method: GET
• Path: /api/ip
• Query parameter: ip
• Auth: Authorization: Bearer YOUR_KEY
• Base: https://ipxapi.com

Requests must include the Authorization header using Bearer YOUR_KEY. Replace YOUR_KEY with your actual token after you register. If you need account setup details or field descriptions, refer to the Documentation.

Make your first request (copy-paste)

The following request uses the documented fixture IP 148.105.12.120. This is a static sample from the docs to demonstrate structure; live results may differ for other IPs or over time.

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

Official JSON response example and field guide

Below is the official product-fixture JSON for the same IP. Do not treat this as your user’s IP; it’s a reproducible example to help you integrate quickly.

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

How to use these fields in your app:

• country, countryCode, region, regionName, city, zip: Use for localization, content rules, and shipping or tax logic. countryCode is ISO alpha-2 (e.g., US).
• lat, lon: Decimal degrees suitable for mapping or approximate distance calculations. Avoid storing as integers; preserve precision.
• timezone: IANA format (e.g., America/Los_Angeles). Use for localizing timestamps or scheduling.
• isp, org, as: Network attribution. Use to segment traffic or understand connectivity. The as field includes the ASN and name in a single string.
• security.is_proxy, security.is_vpn, security.is_cloud_provider: Flags for risk and bot filtering. Do not treat a single flag as a definitive verdict; combine with your own signals.
• inEU, continentCode: Useful for compliance gates and analytics grouping.
• query: Echo of the requested IP, helpful for logs and dashboards.

Quickstart implementation: server or edge

Most deployments call the endpoint on the server or at the edge (CDN functions, gateways) to avoid exposing secrets. The example below is a minimal JavaScript snippet you can run in Node.js or a serverless environment. It demonstrates fetching, basic validation, and a practical mapping from fields to decisions.

// Minimal Node.js example using fetch (Node 18+ or add 'node-fetch')
const ENDPOINT = 'https://ipxapi.com/api/ip?ip=148.105.12.120';

async function lookupIp() {
const res = await fetch(ENDPOINT, {
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_KEY'
},
method: 'GET'
});

// Basic HTTP guard (do not guess status codes; handle generically)
if (!res.ok) {
const text = await res.text().catch(() => '');
throw new Error(`IP lookup failed: HTTP ${res.status} ${text}`);
}

const data = await res.json();

// Extract core geolocation fields
const geo = {
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
};

// Network and security signals
const network = {
isp: data.isp,
org: data.org,
as: data.as,
inEU: data.inEU,
continentCode: data.continentCode
};

const security = data.security || {};
const isProxy = Boolean(security.is_proxy);
const isVpn = Boolean(security.is_vpn);
const isCloud = Boolean(security.is_cloud_provider);

// Example: normalize a region policy and a basic allow/flag decision
const decision = {
allowContent: geo.countryCode !== 'US' ? true : true, // replace with your own logic
requireExtraVerification: isProxy || isVpn
};

return { geo, network, security: { isProxy, isVpn, isCloud }, decision, query: data.query };
}

lookupIp()
.then(result => {
console.log('IP geolocation and security:', result);
})
.catch(err => {
console.error(err);
});

Designing your geolocation and detection pipeline

Align your data flow to where the IP is known. For web apps, capture the client IP at the load balancer or edge (respect trusted proxy headers only if you control the hop). For background jobs or data processing, store the original IP alongside request metadata and run lookups asynchronously to keep hot paths fast.

• Geolocation at ingress: Call /api/ip as early as possible to apply routing and compliance before the request hits your core app.
• Caching: Cache results by IP in your edge cache or key-value store. Use a short TTL because IP-to-location and security flags can change. Avoid indefinite caching.
• Idempotence: Log the query field from the response as the canonical IP you checked.
• Timezones: Use the timezone field to format outbound communications, schedules, and analytics rollups. It is an IANA name, not an offset; use a library that understands daylight saving time.

Using security flags for proxy, VPN, and cloud detection

The security object contains Boolean flags that help you detect network types that often correlate with automation or privacy tools:

• security.is_proxy: Indicates traffic may traverse a proxy. Useful for gating promotions or sensitive actions.
• security.is_vpn: Indicates a VPN. Many legitimate users rely on VPNs; consider step-up verification rather than outright blocking.
• security.is_cloud_provider: Indicates the IP belongs to cloud infrastructure. Combine with rate limits and bot checks for public endpoints.

For IP reputation workflows, combine these booleans with your own signals such as behavioral telemetry, velocity, and account tenure. The API does not return a numeric “reputation score”; build your own thresholding from the available flags and your risk model.

Geolocation details you will actually use

Country and region determine legal and content rules. City, zip, and coordinates are good for personalization and analytics. Keep in mind that geolocation is approximate at the city level; do not use it as the sole factor for user identity or fraud attribution.

• Routing: Route requests to the nearest region in your infrastructure based on lat/lon or countryCode.
• Localization: Default language or currency via countryCode, and schedule via timezone.
• Compliance switches: Use inEU to toggle flows subject to EU-specific requirements.

Network attribution (ISP, org, ASN)

ISP, org, and as add useful context. For example, requests from educational networks, enterprises, or known service providers can be handled differently than consumer broadband. The as field is a single string including the ASN and name; if you need just the numeric ASN, split the string cautiously.

• Allowlisting: Permit admin access only from a known org.
• Analytics: Group events by org or ASN for traffic composition insights.
• Rate strategies: Apply stricter thresholds for large shared networks.

Operational guidance: performance, caching, and observability

To keep latency low, issue requests from the closest runtime to ipxapi.com and reuse HTTP connections. If you operate at the edge, colocate this lookup in the same region as the request entry point. Cache positive responses with a bounded TTL per IP. Because live flags can change, expired entries should be refreshed opportunistically rather than on every request.

• Timeouts: Set reasonable client timeouts and fall back gracefully (e.g., default to global settings if lookup fails).
• Retries: Retry idempotently on transient network failures. Avoid tight retry loops to protect your own capacity.
• Logging: Record query, countryCode, timezone, and security flags for audits and tuning. Do not log secrets.

Account, pricing, and where to start

You can start with a trial for 7 days or 50 requests to validate your integration. The Basic plan is $29.99/mo. Register to obtain YOUR_KEY and begin testing with your own traffic.

Register for access, and review the Documentation for field definitions and implementation notes. If you integrate through a control plane or need management endpoints, see MCP.

FAQ

How do I authenticate requests?

Include the header Authorization: Bearer YOUR_KEY in every call. Replace YOUR_KEY with the token you get after registration.

Which endpoint do I call for geolocation and VPN/proxy detection?

Use GET /api/ip with the ip query parameter, for example: https://ipxapi.com/api/ip?ip=148.105.12.120

Can I cache results?

Yes. Cache by IP with a finite TTL because geolocation records and security flags can change. Refresh periodically and fall back safely if a refresh fails.

Do I get an IP reputation score?

The response includes security flags (is_proxy, is_vpn, is_cloud_provider). There is no numeric score in the response; combine these fields with your own signals to make decisions.

What timezone format is returned?

The timezone field is an IANA timezone (e.g., America/Los_Angeles). Use libraries that support IANA zones for correct daylight saving behavior.

Next steps

Spin up a test with the fixture IP to validate your parsing, then switch the ip parameter to real traffic and layer in caching and security checks. When you are ready, get your key and start your trial at Register. Keep the Documentation handy for field references, and explore MCP if you manage integrations at scale.