IP Address Geolocation API
You need to resolve a user’s IP into reliable geolocation and network context, detect VPN/proxy usage, and make a decision in real time. By the end of this guide, you’ll be able to call the IP Address Geolocation endpoint, parse location and security flags, and integrate the results into routing, personalization, or risk controls.
What you can get from IP Address Geolocation
The endpoint provides structured geolocation and network attributes for a given IP address. You can use these fields to localize content, comply with regional rules, and filter higher-risk traffic:
- Location: country, region, region name, city, postal code, latitude/longitude, timezone.
- Network: ISP, organization, and ASN (as a readable string).
- Security posture: booleans indicating proxy or VPN usage, plus a cloud-provider flag.
- Regulatory context: inEU and continent code to help pick data residency or consent flows.
All examples below use the path /api/ip and the documented fixture IP. Do not treat the fixture as the reader’s IP; it is an example from the docs.
Endpoint and authentication
Base path: /api/ip
HTTP method: GET
Authentication: Authorization: Bearer YOUR_API_KEY
The request accepts a query string parameter ip specifying the IPv4 to look up. Responses are JSON. Always include an Accept: application/json header to avoid content negotiation surprises.
Links you may need during integration:
Quickstart: cURL request
This call looks up the documented fixture IP using the production endpoint. Replace the authorization value with your own key when you run it.
curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"Official JSON sample and key fields
Below is the official, product-fixture response for the same IP. Live flags can change; this is a snapshot from the documentation, not your current network or user.
{
"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’re likely to use:
- country, countryCode, region, regionName, city, zip: String fields for localization or eligibility checks.
- lat, lon: Decimal degrees for mapping or geofencing. Latitude is positive north, longitude is negative west.
- timezone: IANA ID (e.g., America/Los_Angeles) for local-time formatting.
- isp, org, as: Network identifiers and ASN label; useful for rules about consumer vs. business networks.
- security.is_proxy, security.is_vpn, security.is_cloud_provider: Booleans to gate risky or automated traffic.
- inEU, continentCode: Region controls for consent, shipping, or compliance logic.
JavaScript example: fetch and normalize geolocation
This example performs a lookup for the documented fixture IP and extracts the fields most integrations need. Adapt parsing to your own needs. Replace YOUR_API_KEY with your real key when running.
async function lookupIp() {
const API_KEY = 'YOUR_API_KEY';
const url = 'https://ipxapi.com/api/ip?ip=148.105.12.120';
const res = await fetch(url, {
headers: {
'Accept': 'application/json',
'Authorization': `Bearer ${API_KEY}`
},
// Keep timeouts and retries at your HTTP client layer or fetch wrapper.
});
if (!res.ok) {
// Surface the HTTP status to your logs/alerts and apply your retry policy.
throw new Error(`ipXapi lookup failed: ${res.status}`);
}
const data = await res.json();
// Minimal normalization commonly needed in apps:
const geo = {
ip: data.query,
country: data.country,
countryCode: data.countryCode,
region: data.region,
regionName: data.regionName,
city: data.city,
postalCode: data.zip,
latitude: data.lat,
longitude: data.lon,
timezone: data.timezone,
isp: data.isp,
org: data.org,
asn: data.as, // e.g., "AS14782 MailChimp"
inEU: data.inEU === true,
continentCode: data.continentCode,
// Security signals:
isProxy: data.security && data.security.is_proxy === true,
isVpn: data.security && data.security.is_vpn === true,
isCloudProvider: data.security && data.security.is_cloud_provider === true
};
return geo;
}
// Example usage:
lookupIp()
.then(geo => {
console.log('Country/Region:', geo.country, geo.regionName);
console.log('Lat/Lon:', geo.latitude, geo.longitude);
console.log('Timezone:', geo.timezone);
console.log('ISP/Org/ASN:', geo.isp, geo.org, geo.asn);
console.log('Security flags - Proxy/VPN/Cloud:', geo.isProxy, geo.isVpn, geo.isCloudProvider);
})
.catch(err => {
console.error(err);
});Input, output, and integration notes
Input format: The ip parameter expects an IPv4 address in dotted-quad form. The documented sample uses 148.105.12.120. If the IP is missing or malformed, handle the HTTP error path and return a safe default upstream in your application logic.
Output format: The service responds with application/json. Numeric fields lat and lon are in decimal degrees. timezone is an IANA timezone string. Booleans in the security object indicate the presence of proxies, VPNs, or cloud providers for the queried IP address at the time of the lookup.
Localization: Use the IANA timezone to compute local time display and time-window rules. If localizing language or currency, derive only what you are comfortable enforcing; a countryCode of US, for instance, does not imply a language or locale preference without additional context.
Personalization vs. enforcement: Security flags help with fraud controls and abuse prevention. Treat them as signals in a policy engine, not as absolute truths; apply thresholds and fallback experiences.
Performance, caching, and consistency
Latency: The endpoint is suitable for synchronous usage in server-side flows. Minimize client-side calls directly from browsers; resolve IPs on the server where you manage keys and retry policies safely.
Caching: Cache by exact IP. For stable endpoints like country or timezone, a TTL between minutes and hours can reduce traffic while still tracking dynamic routing and reassignment. If your application requires up-to-the-minute accuracy on security flags, keep a shorter TTL and revalidate on suspicious events.
Idempotency: GET requests are read-only and safe to retry on network timeouts. Implement exponential backoff and jitter at your HTTP client layer.
Consistency: Live flags such as security.is_proxy can change as providers reassign ranges or detection models update. Avoid persisting these booleans indefinitely; store them with a timestamp and refresh periodically.
Error handling and fallbacks
HTTP errors: Surface HTTP status codes to logs and respond with a safe default in upstream logic. If your business rules depend on region restrictions, assume the most conservative path when lookups fail.
Input validation: Strip surrounding whitespace from the ip parameter and validate the dotted-quad format before sending the request. Avoid batch-submitting invalid addresses, which wastes quota.
Security and privacy practices
Secret management: Store YOUR_API_KEY in server-side secrets management and never expose it in client-side code or public repositories. The Authorization header uses a Bearer token.
Data handling: Treat geolocation data as sensitive. Log only what you need for debugging, and consider hashing the IP if storing long-term analytics. If you operate in the EU, use inEU and timezone to drive consent and data-routing logic.
Abuse mitigation: Combine is_proxy, is_vpn, and is_cloud_provider with your existing device intelligence and session risk models. Consider step-up verification or rate limiting, not outright blocking, unless your risk tolerance demands it.
Pricing, trial, and account setup
Basic plan: $29.99/mo.
Trial: 7 days or 50 requests, whichever occurs first.
You can create an account and obtain an API key here: Register. After registering, place the key in the Bearer Authorization header as shown in the examples.
Testing and operational tips
- Fixture testing: Use the documented fixture IP 148.105.12.120 for repeatable tests. Do not treat it as your current IP.
- Structured logs: Log request start/end timestamps, IP, and a compact summary of countryCode, region, and security flags to speed up incident triage.
- Normalization: Normalize region and country codes upstream into your canonical enums to avoid mismatches in downstream services.
- Alerting: Set alerts on sudden shifts in country distribution or spikes in is_vpn/is_proxy to catch routing changes or attack waves early.
FAQ
Can I call the endpoint without specifying an IP?
If you do not supply ip, you won’t get a valid lookup for this integration. Keep a clear contract in your code to always pass a validated IP to /api/ip.
How should I treat the security flags?
Use security.is_proxy, security.is_vpn, and security.is_cloud_provider as inputs to a risk policy. Avoid permanent storage without timestamps; the flags can change as networks and detections update.
What timezone format is returned?
The timezone field uses IANA identifiers (for example, America/Los_Angeles). Use a timezone-aware library to format local times in your UI or server processes.
Is there an ASN field?
The as field contains the ASN and a descriptive label (e.g., “AS14782 MailChimp”). Parse it as a string in your logs or rules.
Where do I find environment and tooling endpoints?
Refer to the service control plane here: MCP, and consult the API reference: Documentation.
Ready to integrate IP Address Geolocation with proxy/VPN detection and ASN context? Start your trial and get an API key now: Register.