IP Location API

You need reliable IP geolocation with proxy/VPN detection to personalize content, enforce regional rules, and reduce fraud. By the end of this guide, you will query the IP Location endpoint, parse location and security fields, and safely ship an integration that handles caching, timezones, and changing live flags.

What the IP Location endpoint returns and when to use it

The IP Location endpoint resolves an IPv4 address to country, region, city, ZIP, coordinates, timezone, and network identifiers, alongside basic security flags for proxy, VPN, and cloud-provider detection. Use it to tailor experiences per region, gate content by jurisdiction, or add lightweight risk signals to login and checkout flows.

This guide uses only the documented path and fixture IP:

• Path: /api/ip
• Fixture IP: 148.105.12.120

Live flags can change per request, so treat responses as dynamic telemetry rather than static metadata.

Quickstart: call the IP Location endpoint

Authentication is Bearer. Replace YOUR_KEY in the cURL block with your token, or YOUR_API_KEY in the code sample. For account setup, pricing, and limits, see the links below.

Copy and run:

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

Official response sample

This is the official product-fixture JSON for the documented IP. Do not assume these values match your users’ IPs; use it only as a reference for fields and types.

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

Fields you will commonly use:

• country, countryCode, region, regionName, city, zip: text fields for location labels and postal code.
• lat, lon: decimal degrees (WGS84). Use as-is for maps or geo-fencing.
• timezone: IANA identifier (e.g., America/Los_Angeles). Convert timestamps to local time with a TZ-aware library.
• isp, org, as: network owner and autonomous system string.
• security.is_proxy, security.is_vpn, security.is_cloud_provider: booleans for basic traffic classification.
• query: the IP you looked up; useful for logging and cache keys.

JavaScript example: fetch and normalize geolocation + security

This snippet queries the same endpoint and extracts the minimum fields you’ll likely need for personalization and risk checks. Replace YOUR_API_KEY with your token.

async function lookupIp(ip) {
const API_KEY = 'YOUR_API_KEY';
const url = `https://ipxapi.com/api/ip?ip=${encodeURIComponent(ip)}`;

const res = await fetch(url, {
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
// If you run this server-side, set a reasonable timeout/retry policy around fetch.
});

if (!res.ok) {
// Surface HTTP errors with enough detail for observability without leaking secrets.
throw new Error(`IP lookup failed with status ${res.status}`);
}

const data = await res.json();

if (data.status !== 'success') {
// The API indicates non-success in the payload; handle gracefully.
throw new Error('IP lookup did not return success status');
}

// Normalize for your app.
return {
ip: data.query,
countryCode: data.countryCode,
regionCode: data.region, // e.g., US-CA
regionName: data.regionName, // e.g., California
city: data.city,
postalCode: data.zip,
latitude: data.lat,
longitude: data.lon,
timezone: data.timezone, // IANA TZ name
network: {
isp: data.isp,
org: data.org,
as: data.as
},
security: {
isProxy: data.security?.is_proxy === true,
isVpn: data.security?.is_vpn === true,
isCloudProvider: data.security?.is_cloud_provider === true
},
metadata: {
inEU: data.inEU === true,
continentCode: data.continentCode
}
};
}

// Example use:
lookupIp('148.105.12.120')
.then(info => {
console.log('Geo:', info.countryCode, info.regionCode, info.city);
console.log('TZ:', info.timezone);
console.log('Security flags:', info.security);
})
.catch(err => {
console.error(err);
});

Request format and authentication

Endpoint: https://ipxapi.com/api/ip with a single query parameter ip for the IPv4 address you want to resolve. The method is GET. Include an Authorization: Bearer token header. The Accept: application/json header ensures a JSON response.

Example path used throughout: /api/ip?ip=148.105.12.120

Keep your key on the server side for production and never commit it to client bundles. For client-only use cases, proxy requests through your backend.

Interpreting geolocation and security fields

Location labels are UTF-8 strings suitable for direct UI display after standard escaping. Coordinate values (lat, lon) are decimal degrees with latitude in the range [-90, 90] and longitude in [-180, 180]. Timezone values are IANA TZ names suitable for libraries like Intl.DateTimeFormat or moment-timezone.

Security flags are booleans that change over time as IP ownership and routing change. Treat them as signals rather than absolute truth. For example, consider combining is_vpn or is_proxy with behavioral checks before blocking a user.

Caching, freshness, and error handling

• Cache keys: include both endpoint path and the ip parameter (e.g., /api/ip?ip=203.0.113.5).
• TTL: many apps cache per-IP responses for minutes to hours. Because IP characteristics change, use modest TTLs and re-check on important events (login, payment).
• Stale-while-revalidate: serve cached data immediately and refresh in the background for better latency.
• Error handling: on network or 5xx errors, fall back to last-known good data if available, and log the failure with IP and correlation IDs.
• Geo consistency: because live flags can change, design idempotent flows that can tolerate location/security deltas between steps.

Minimal data model for your application

Store only what you use. A simple schema could include ip, countryCode, regionCode, city, postalCode, lat, lon, timezone, as, isp, org, and the three security booleans. Include a fetchedAt timestamp (UTC) to manage refresh policies and to debug stale results.

Pricing, trial, and environment setup

Basic is $29.99/mo. The trial is 7 days or 50 requests. Start by obtaining an API key, add it to your secrets manager, and verify a single call in your development environment before rolling out to staging.

Useful links:

• Register
• Documentation
• MCP

Putting it together: integrating into a request pipeline

Login or checkout flow

• On key events (login, password reset, payment), lookup the client IP using /api/ip.
• Normalize the payload to your internal schema and store alongside the event.
• Apply rules: block or challenge if security.is_vpn or security.is_proxy is true and the user’s historical pattern is residential and local; otherwise reduce trust score or add 2FA.
• Localize times using timezone for emails and receipts to reduce confusion around deadlines and delivery windows.

Content localization

• Cache per-IP location for short periods (e.g., 5–30 minutes) to keep pages fast.
• Decide regional settings (currency display, language choice) from countryCode and region.
• Honor legal constraints by geofencing content based on countryCode and, if necessary, regionName.

Testing with the documented fixture

Use the provided fixture IP 148.105.12.120 for automated tests. Snapshot the specific fields you assert on (e.g., property presence and types) instead of exact booleans or names that can change over time. For example, assert that data has a timezone string and that security contains the expected keys, not that a flag is permanently true or false.

Operational notes that save time

• Units: lat/lon are decimal degrees; no conversion needed for most mapping SDKs.
• Timezones: the timezone field is an IANA name; avoid manual offsets which shift with DST.
• No pagination: single-IP lookups return one document; design the client without pagination logic.
• Rate limiting: if you approach plan limits, introduce a local cache and defer low-priority lookups.
• PII handling: an IP address can be sensitive; store only what you need and set appropriate retention.

FAQ

Does the endpoint accept IPv6?
Use the documented interface and refer to the Documentation for current IP version coverage. This article’s examples use the provided IPv4 fixture.

How often should I refresh the lookup?
On critical events (login, payment) and periodically for active sessions. Cache for minutes to hours depending on your risk tolerance and traffic patterns.

Can I rely on proxy/VPN flags for hard blocks?
Treat is_proxy and is_vpn as signals. Combine them with behavioral data and consider step-up authentication instead of automatic blocks.

Which timezone format should I use in my app?
Use the returned IANA timezone name directly with a TZ-aware library to handle DST correctly.

Where can I monitor or manage my API access?
Use your account portal and the MCP endpoint as applicable for your integration context.

Ready to implement IP geolocation with proxy and VPN detection? Create your key and start integrating the /api/ip endpoint now: Register. For field-by-field details and additional options, see the Documentation.