IP to Geolocation API

You need reliable IP geolocation with proxy/VPN detection and ASN details so you can personalize content, block abusive traffic, or comply with regional rules. By the end of this guide, you will be able to query an IP address, parse country/region/city coordinates, read security flags for proxies and VPNs, and integrate the same endpoint into your backend or edge middleware.

What this API does for geolocation, proxy/VPN checks, and ASN

The IP lookup returns geographic fields (country, region, city, latitude/longitude, timezone) plus network identity signals (ISP, organization, AS string) and basic security flags (is_proxy, is_vpn, is_cloud_provider). These cover common needs:

• IP geolocation: country, region, city, zip, lat/lon, timezone.
• Proxy/VPN detection: see security.is_proxy and security.is_vpn.
• ASN context: read the as field and ISP/org for routing and network ownership cues.
• IP reputation basics: while no score is returned, security flags and network fields help you create simple allow/deny heuristics.

This article stays within the IP geolocation category and uses a single, documented endpoint so you can integrate quickly without guessing parameters or response formats.

Endpoint, auth, and base URLs

Use the following HTTP endpoint for a single-IP lookup:

• Path: /api/ip
• Query parameter: ip
• Method: GET
• Headers: Accept: application/json, Authorization: Bearer YOUR_KEY

For developer onboarding and reference, see the Documentation. The managed control plane for this API is available at MCP.

Quickstart: run a cURL lookup

The cURL below targets the documented fixture IP and uses Bearer authentication. Replace YOUR_KEY with your token once you’ve created an account, but keep the same endpoint, parameters, and headers.

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

Official JSON response (fixture)

This is the official product-fixture JSON for 148.105.12.120. Live responses can change based on IP ownership and updated data. 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
}
}

What you will use most often:

• country, countryCode, region, regionName, city, zip: location and administrative divisions.
• lat, lon: coordinates for mapping and distance checks.
• timezone: localize times and schedule logic; value uses IANA format.
• isp, org, as: network ownership and ASN context; useful for routing and policy.
• security.is_proxy, security.is_vpn: quick traffic classification for rules and risk filters.
• query: the IP you looked up (echoed).

Use it in application code

The example below calls the same endpoint and reads the most common fields needed for geolocation, proxy/VPN detection, and ASN context. Replace YOUR_API_KEY with your token. This pattern works well in server-side code or edge middleware where you control secrets.

/**
* Minimal Node.js/JavaScript example using fetch (Node 18+ or any runtime with fetch).
* Reads geolocation fields, security flags, and ASN+ISP context.
*/
async function lookupIp(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) {
// Handle non-200 without assuming a specific error schema
const text = await res.text();
throw new Error(`Lookup failed: ${res.status} ${res.statusText} - ${text}`);
}

const data = await res.json();

// Safely read the fields that matter
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,
isProxy: data.security?.is_proxy === true,
isVpn: data.security?.is_vpn === true,
isCloud: data.security?.is_cloud_provider === true
};

return result;
}

// Example usage with the documented fixture IP
lookupIp('148.105.12.120')
.then(info => {
console.log('Geo:', {
country: info.country,
region: info.regionName,
city: info.city,
coordinates: [info.lat, info.lon],
timezone: info.timezone
});
console.log('Network:', { isp: info.isp, org: info.org, as: info.as });
console.log('Security flags:', { proxy: info.isProxy, vpn: info.isVpn, cloud: info.isCloud });
})
.catch(err => {
console.error(err);
});

How to interpret results for geolocation and traffic controls

Geolocation:

• Country and region-level checks are stable for content gating and compliance pages.
• City, zip, lat/lon are sufficient for localization and high-level map placement.
• Timezone is an IANA string (for example, America/Los_Angeles) and should be used for server-side scheduling and date formatting. Avoid inferring timezone numeric offsets yourself; use the string with a timezone-aware library.

Proxy/VPN detection:

• security.is_proxy and security.is_vpn are booleans intended for quick rule checks.
• Use them as signals in rate limiting, login hardening, or checkout reviews. If false, treat traffic as residential/corporate unless other evidence indicates risk.
• security.is_cloud_provider can help you handle cloud-origin traffic differently (for example, challenge or throttle automated agents).

ASN and network identity:

• Use the as field and ISP/org to understand network ownership and routing context.
• For allowlists or stricter bot policies, match on as, isp, or org values. Keep exact string comparisons tolerant of minor variations (whitespace, capitalization).

Deployment patterns and where to run the lookup

Server or edge:

• Run lookups on the server or at the edge to keep your bearer token private. Client-side calls expose keys and should be avoided.
• At the edge, you can enrich requests with geolocation-derived headers for downstream services, reducing repeated lookups within a request flow.

Batch vs on-demand:

• For high-traffic endpoints, cache results for a short TTL because IP ownership can shift. The right TTL depends on your tolerance for staleness; keep it reasonably short when using security flags for policy.
• Normalize IP strings (lowercase, trimmed) and cache by the canonical IP value to improve hit rates.

Error handling:

• Handle non-200 responses and timeouts gracefully. Do not assume a specific error schema; log status code and body text for observability.
• Default to conservative behavior when geolocation is unavailable (for example, show a neutral experience rather than blocking) unless your policy requires strict gating.

Testing with the documented fixture IP

Use 148.105.12.120 for replicable examples. The official response shown earlier is a product fixture. Live flags can change, so do not hard-code security decisions to the fixture JSON. Instead, assert that the expected fields exist and that your code handles booleans and strings correctly.

When running end-to-end tests, pin your expectations to field presence and type (for example, timezone is a non-empty string; security keys are booleans) rather than specific values that could change when the data source updates.

Practical implementation details that prevent surprises

• Character encoding: Responses are JSON UTF-8; set Accept: application/json to avoid content negotiation issues.
• IP versions: Validate inputs are IPv4/IPv6 as appropriate before calling. If your app collects user-entered IPs, trim whitespace and reject malformed strings early.
• Timezone handling: Always pass the IANA timezone string into your date library; do not recompute offsets manually.
• Coordinates: lat and lon are decimal degrees. When storing, keep sufficient precision to avoid rounding artifacts in distance calculations.
• Security booleans: Treat missing security as unknown/false. Write rules that handle undefined fields defensively.
• Privacy: Avoid logging full IPs in plaintext for jurisdictions with privacy constraints. If needed, hash IPs for analytics while keeping the raw IP in protected storage only when justified.
• Caching: Use a short TTL cache layer for hot IPs. In CDNs or edge functions, a per-POP cache reduces latency.

Product plans, trial, and where to manage access

You can start with a trial (7 days or 50 requests) and then move to the Basic plan at $29.99/mo. Create an account to obtain YOUR_API_KEY and manage tokens. The managed control plane is available at MCP for operations tasks. For endpoints and field details, consult the Documentation.

Security and compliance considerations

Because IP-derived signals can influence access controls, ensure your policies are transparent and offer fallbacks. For example, when security.is_vpn is true, you might challenge with multi-factor authentication rather than block outright, depending on your use case and applicable regulations.

Log decisions and inputs used for policy, but restrict access to those logs. When exporting data, avoid combining IPs with personally identifiable information unless you have a clear legal basis.

Operational tips for production

• Circuit breakers: If outbound calls fail repeatedly, degrade gracefully and serve default content to preserve availability.
• Observability: Track lookup latency, success rate, and cache hit ratio. Alert on prolonged degradation.
• Schema stability: Guard your parser against additional fields you may see later. Read only the keys you need and ignore unknown keys.
• Rollouts: When adding new policy rules (for example, blocking is_proxy), start in monitor-only mode, collect stats, then enforce.

Frequently asked questions

How do I pass authentication?
Use an Authorization header with Bearer YOUR_API_KEY. Do not put tokens in URLs. Keep tokens server-side.

Which endpoint should I call for geolocation and proxy/VPN checks?
Call /api/ip with the ip query parameter and Accept: application/json. The same response includes geolocation, ASN context, and security flags.

Can I cache results?
Yes. Use a short TTL cache because network ownership and security flags can change. Cache by the normalized IP string.

Does the response include an IP reputation score?
No score is returned. Use security.is_proxy, security.is_vpn, and network fields (isp, org, as) as signals in your own risk model.

Where do I manage keys and see usage?
Register for access and manage your key. Use the control plane at MCP for operational tasks and consult the Documentation for endpoint details.

Get started

Spin up your first lookup now and wire IP geolocation with proxy/VPN checks into your stack. Create your account to get a token, run the cURL example, then drop the JavaScript snippet into your service. Register