IP Address Lookup API
You need to geolocate an IP, detect proxies/VPNs, and surface ISP/ASN details from a reliable endpoint so you can personalize content, enforce geo rules, or filter risky traffic. By the end of this guide, you’ll call the IP Address Lookup endpoint, parse the geolocation and security fields, and ship a production-ready integration with caching and error handling.
What the IP Address Lookup returns and why it matters
The IP Address Lookup focuses on geolocation and network reputation signals in a single response. Core fields include:
- Country, region, city, and zip for location-aware logic.
- Latitude/longitude for mapping and proximity checks (degrees, WGS84).
- Timezone as an IANA string for localizing time (e.g., America/Los_Angeles).
- ISP, org, and AS (autonomous system) details for network profiling.
- Security flags: is_proxy, is_vpn, and is_cloud_provider for bot/risk filtering.
The endpoint serves geolocation, proxy detection, VPN detection, ASN, and basic IP reputation cues through one call, avoiding multiple network requests in your critical request path.
Endpoint, method, and authentication
Endpoint path: /api/ip. Method: GET.
Query parameter:
- ip: The IPv4 you want to look up.
Headers:
- Accept: application/json
- Authorization: Bearer YOUR_KEY
Reference links:
Quickstart: one-line cURL
Use the documented fixture IP for testing. Replace YOUR_KEY with your bearer token. This is a fixture, not your current IP, and live flags can change.
curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"Official JSON sample
Here is the official product-fixture response for the documented IP. Do not treat this as your user’s IP during development; it’s a stable fixture for examples, while live flags can change.
{
"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 notes you will actually use:
- country, countryCode, region, regionName, city, zip: direct geolocation labels.
- lat, lon: floating-point degrees for maps and distance checks.
- timezone: IANA identifier for consistent date/time formatting.
- isp, org, as: network/ASN metadata for profiling or allow/deny logic.
- security.is_proxy, security.is_vpn, security.is_cloud_provider: detection flags for traffic risk and policy enforcement.
- query: the IP you looked up (echoed for traceability).
JavaScript example: fetch and apply geolocation and security rules
This example calls the same endpoint with the fixture IP, extracts the fields you need, and shows how to branch on the security flags. Replace YOUR_API_KEY with your token.
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 transport-level errors (network, 4xx/5xx)
throw new Error(`Request failed with status ${res.status}`);
}
const data = await res.json();
// Basic schema checks
if (data.status !== 'success') {
throw new Error('Lookup did not return success status');
}
// Extract key 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
};
const network = {
isp: data.isp,
org: data.org,
as: data.as
};
const security = data.security || {};
// Example policy: block proxy/VPN or known cloud-provider egress
const isRisky = !!(security.is_proxy || security.is_vpn || security.is_cloud_provider);
return { ip: data.query, geo, network, security, isRisky };
}
// Usage with the documented fixture IP
lookupIp('148.105.12.120')
.then(result => {
console.log('Geolocation:', result.geo);
console.log('Network:', result.network);
console.log('Security flags:', result.security);
if (result.isRisky) {
console.log('Apply stricter checks or step-up auth.');
} else {
console.log('Proceed with normal flow.');
}
})
.catch(err => {
console.error('Lookup error:', err.message);
});Implementation details that save time
1) Data freshness and caching
IP-based geolocation and ASN mapping do not change frequently for most residential users, but can change for mobile, enterprise NATs, and cloud ranges. Cache successful lookups for a short period in your edge or application cache to reduce latency. If any policy depends on security flags (proxy/VPN/cloud), use a shorter TTL so you can react to changes promptly.
2) Timezone handling
The timezone field is an IANA string (for example, America/Los_Angeles). Use it directly with your date/time library to avoid hardcoding offsets. Daylight saving adjustments are managed by the IANA database, not by fixed numeric offsets.
3) Coordinate units
lat and lon are standard decimal degrees. If you need distance calculation, use a great-circle formula (for example, haversine) on WGS84 coordinates. Keep coordinates in double precision if you’re chaining geospatial operations.
4) Security enforcement patterns
- Block or challenge if security.is_proxy or security.is_vpn is true.
- For traffic where human presence is required (checkout, account creation), treat security.is_cloud_provider as higher risk and apply step-up verification.
- Log the as, isp, and org along with your decision for audits.
5) Request tracing
Persist the query field in your logs so you can correlate user sessions, CDNs, and upstream proxies to the resolved IP address. This is often critical for debugging routing and regional discrepancies.
Production guidance
- Resilience: Implement retries with exponential backoff on transient network failures. Do not retry on explicit client errors.
- Timeouts: Set a reasonable client timeout so IP lookups do not block your core flow indefinitely.
- Fallbacks: If the lookup fails, define a safe default (for example, show generic content) rather than halting the user experience.
- Privacy: IP addresses can be personal data in some jurisdictions. Store only what you need and review your retention policies.
- Testing: Use the documented fixture IP during development to validate your parser and policies. Live data will vary.
Plan, trial, and account setup
The Basic plan is $29.99/mo. The trial is 7 days or 50 requests. Start by creating an account, obtain your API key, and set the Authorization header to Bearer YOUR_KEY in each request.
Links:
MCP endpoint for operational readiness
For status and operational references, see the MCP entry point: MCP. Use it alongside your monitoring to surface issues early and keep your geolocation-dependent flows healthy.
FAQ
Do I need to pass any headers besides Authorization?
Send Accept: application/json and Authorization: Bearer YOUR_KEY. The example cURL shows the exact header names and values to use.
Is the documented fixture IP my current IP?
No. 148.105.12.120 is a product fixture for examples. Do not treat it as the reader’s IP, and expect live flags to differ in production.
How do I detect proxies, VPNs, or cloud-provider egress?
Use the security object: is_proxy, is_vpn, and is_cloud_provider. Branch your policy based on these booleans.
What timezone format is returned?
An IANA timezone string (for example, America/Los_Angeles). Feed it to your date/time library to handle offsets and DST correctly.
Can I cache lookups?
Yes. Cache results to reduce latency, but use a shorter TTL if your policy depends on security flags. Always revalidate periodically to adapt to network changes.
Get your API key and ship your integration today. Create an account, run the cURL against /api/ip with your bearer token, and plug the response into your geolocation and risk logic: Register.