Geo IP API

You need reliable IP geolocation with proxy/VPN detection and ASN context to block fraud, localize content, or route users. By the end of this guide you will query a real Geo IP endpoint, parse the response for country/region/city, read proxy/VPN flags, and wire the results into a production-ready decision path.

What you will build with the Geo IP endpoint

This article walks through a single geolocation endpoint that returns location, ISP/organization, ASN, and basic network security flags for an input IP. You will:

• Authenticate with a bearer token over HTTPS.
• Query a specific IP and parse geolocation fields (country, region, city, coordinates, timezone).
• Evaluate proxy/VPN/cloud-provider signals for risk decisions.
• Use the ASN string to add network context without inventing a reputation score.
• Implement a small client in JavaScript or Python and add caching/backoff behaviors.

Endpoint and authentication

The Geo IP lookup uses a single HTTP GET endpoint:

• Path: /api/ip
• Query parameter: ip (IPv4 or IPv6 address). This guide uses the documented fixture IP.
• Authentication: HTTP header Authorization: Bearer YOUR_API_KEY
• Accept header: Accept: application/json

If you do not have an API key, you can start with the trial (7 days or 50 requests) and upgrade to the Basic plan at $29.99/mo when you are ready. Create your key here: Register.

For endpoint parameters, response fields, and behavior details, see the official Documentation. You can also access the MCP at MCP.

Official cURL example

Use the documented fixture IP for testing. Copy this request exactly to confirm your integration path and headers:

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

Official sample JSON response

Below is the official sample for the same fixture IP. Live flags can change at runtime; treat this as a product fixture, not 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
}
}

Key fields to consume:

• country, countryCode, region, regionName, city, zip: Use for content localization, tax/VAT logic, or analytics.
• lat, lon: Decimal degrees for distance checks and map pins.
• timezone: IANA identifier for local-time conversions.
• isp, org, as: Network context and ASN string for coarse IP reputation rules without a score.
• security.is_proxy, security.is_vpn, security.is_cloud_provider: Binary indicators to gate signups, payments, or admin actions.
• query: The IP you sent, echoed for logging.

JavaScript integration example

This minimal fetch client calls the same endpoint and reads the geolocation and security fields you will typically branch on. Replace YOUR_API_KEY with your real key when you are ready to deploy.

// Simple Geo IP lookup using fetch and the documented fixture IP
async function lookupIp() {
const url = 'https://ipxapi.com/api/ip?ip=148.105.12.120';
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
}
});

if (!res.ok) {
// Avoid leaking full response bodies in logs in production
throw new Error('Geo IP request failed with status ' + res.status);
}

const data = await res.json();

// Extract fields you will commonly use
const location = {
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
};

const network = {
isp: data.isp,
org: data.org,
asn: data.as, // ASN string, not a numeric ID
inEU: data.inEU,
continentCode: data.continentCode
};

const security = data.security || {};
const riskSignals = {
isProxy: security.is_proxy === true,
isVpn: security.is_vpn === true,
isCloudProvider: security.is_cloud_provider === true
};

// Example branching without inventing a score:
// 1) Block sensitive actions from VPNs or proxies.
// 2) Allow read-only actions but challenge (OTP/CAPTCHA) when from cloud providers.
if (riskSignals.isProxy || riskSignals.isVpn) {
console.warn('High-risk network for IP', data.query);
} else if (riskSignals.isCloudProvider) {
console.info('Cloud-origin traffic; consider step-up auth for IP', data.query);
}

return { location, network, riskSignals };
}

lookupIp()
.then(result => {
console.log('Geo IP location:', result.location);
console.log('Network:', result.network);
console.log('Security:', result.riskSignals);
})
.catch(err => {
console.error('Lookup failed:', err);
});

Mapping geolocation and security to product decisions

Once you parse the JSON, add small rules that are easy to reason about and audit. Some common patterns:

• Content localization: Use countryCode and timezone to preselect language and local time. Store a short-lived cache entry keyed by IP.
• Checkout or signup guardrails: If security.is_vpn or security.is_proxy is true, require a step-up (e.g., email OTP) before accepting payment or granting elevated roles.
• Admin panel lockdown: Deny write actions outright from security.is_cloud_provider true unless the user is on an internal allowlist. Many automated scripts run from cloud IPs.
• ASN heuristics: Read as to classify network types. Use it as an explanatory signal in risk logs rather than as a sole blocker.

Operational details that save time

These implementation notes help you ship faster and avoid surprises:

• Timezone format: timezone uses an IANA identifier (for example, America/Los_Angeles). Most date libraries can convert server UTC timestamps to local time using this string.
• Coordinates: lat and lon are decimal degrees. For radius checks, compute great-circle distance and choose a tolerance suitable for IP-level precision.
• Caching: Cache successful lookups for a short TTL (for example, hours) because IP-to-location mappings can change. The security flags can also change; avoid long TTLs for risk decisions.
• Idempotency: The endpoint is a pure GET; safe to retry on transient network errors with exponential backoff.
• Input validation: Only query public IPs. For local addresses, skip the external lookup and default to a safe flow.
• Logging: Log query, countryCode, and the three security booleans for audits. Avoid persisting user IPs longer than necessary per your privacy policy.

Error handling and testing strategy

When wiring production error handling, treat any non-2xx as a soft failure and default to conservative rules:

• If the API call fails, continue with a neutral location and stricter risk checks (for example, challenge high-value actions).
• For malformed input IPs, reject early in your edge or API gateway.
• Set a short timeout on your outbound request so page loads are not blocked by network stalls.

For testing, always start with the documented fixture IP to ensure your headers, URL, and JSON parsing match the spec before switching to live traffic. Do not treat fixture values as your environment’s ground truth; they exist to validate your integration path.

Security, privacy, and governance notes

Use the proxy/VPN/cloud-provider flags to reduce fraud while respecting privacy:

• Apply the minimum data you need for a decision. For example, country-level routing rarely requires storing precise coordinates.
• Scope your logs to essential fields and implement automated redaction for IPs after a retention window you define.
• If you perform geofencing, audit your allow/deny lists with the echoed query and as to detect overbroad rules.

Working with MCP

The MCP is available at MCP. Use it alongside the main endpoint for ecosystem access and to manage your usage as needed. Keep your bearer token secure and rotate it regularly within your secrets store.

Pricing and trial

You can evaluate the Geo IP endpoint on a trial that lasts 7 days or 50 requests, whichever comes first. The Basic plan is $29.99/mo when you are ready to expand. Start here: Register. For endpoint and field references, see the Documentation.

FAQ

What authentication header should I use?
Send Authorization: Bearer YOUR_API_KEY along with Accept: application/json.

Which endpoint should I call for a single IP geolocation?
Use GET /api/ip with the ip query parameter. This guide uses the documented fixture IP 148.105.12.120.

Can I rely on proxy/VPN/cloud-provider flags for all risk blocking?
Use them as strong signals, but couple them with your own session and behavior checks. Cache results for a short TTL because these flags can change.

How should I treat the ASN field?
Read the as string for network context in logs and allow/deny rules. Do not invent a reputation score from it.

Is there a free way to test?
Yes. Use the trial (7 days or 50 requests) to validate your code paths and dashboards before moving to the Basic plan.

Get started

Implement the cURL and JavaScript samples above with your bearer token, then wire the location and security fields into your routing and risk checks. When you are ready, create your key here: Register and keep the Documentation and MCP links handy for reference.