IP to Location API
You need to turn an IP address into useful, production-grade geolocation and network signals (country, region, city, timezone, ISP, ASN) while also detecting proxy/VPN and cloud provider usage. By the end of this guide, you’ll be able to query an IP to location API endpoint, parse the official response fields you actually need, and integrate them with reliable caching and error handling patterns.
What you can build with IP geolocation and network signals
Common use cases include regional content controls, pricing localization, timezone-aware timestamps, fraud heuristics (proxy/VPN detection), and compliance prompts. The /api/ip endpoint returns the country, region, city, latitude/longitude, timezone, and network metadata (ISP, organization, and ASN string), along with a compact security object that flags proxies, VPNs, and cloud providers.
This post keeps the scope on geolocation and IP reputation signals only. All examples target /api/ip and the documented fixture IP, and you’ll see exactly how to request and consume the response in your backend or edge layer.
Endpoint, parameters, and authentication
Base endpoint for geolocation and network signals:
- Path: /api/ip
- Query parameter: ip (IPv4 address string; fixture shown below)
- HTTP method: GET
- Auth: Authorization: Bearer YOUR_API_KEY
- Accept: application/json
Pricing basics: the Basic plan is $29.99/mo, and there’s a trial for 7 days or 50 requests. If you don’t have an API key yet, register before continuing.
Quick start with cURL
Copy, paste, and run the official request to see a real, documented fixture response. Replace the Authorization value with your key when you’re ready to go live.
curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"Official JSON response (fixture) and what to read
This is the documented product-fixture JSON for the IP 148.105.12.120. Live flags can change, so treat it as an example for integration and field mapping, not as your user’s 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
}
}Field highlights you’ll typically wire up:
- country, countryCode, region, regionName, city, zip: Use for localization rules and addressing.
- lat, lon: Decimal degrees suitable for mapping SDKs or distance calculations.
- timezone: IANA TZ identifier (e.g., America/Los_Angeles) for local time rendering.
- isp, org, as: Network and ASN context. Useful for risk decisions and network analytics.
- security.is_proxy, security.is_vpn, security.is_cloud_provider: Boolean signals for session hardening and risk scoring.
- inEU, continentCode: Regional compliance and routing policies.
- status: Check for "success" before using the payload.
Minimal integration in JavaScript (fetch)
This example calls the same /api/ip endpoint, reads the core location fields and security flags, and shows how to branch on "success". Replace YOUR_API_KEY with your key when you’re ready.
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-2xx responses without assuming specific error codes or formats
throw new Error(`Request failed with status ${res.status}`);
}
const data = await res.json();
if (data.status !== "success") {
// Defensive check since status is present in the fixture
throw new Error("Lookup did not return success");
}
// Extract the fields most apps use
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,
asn: data.as, // String with ASN and name
inEU: data.inEU,
continentCode: data.continentCode,
security: {
isProxy: data.security?.is_proxy === true,
isVpn: data.security?.is_vpn === true,
isCloudProvider: data.security?.is_cloud_provider === true
}
};
return result;
}
// Example usage with the documented fixture IP:
lookupIp("148.105.12.120")
.then(info => {
console.log("Geolocation:", {
country: info.country,
region: info.regionName,
city: info.city,
timezone: info.timezone,
lat: info.lat,
lon: info.lon
});
console.log("Network:", { isp: info.isp, org: info.org, asn: info.asn });
console.log("Security flags:", info.security);
})
.catch(err => {
console.error("IP lookup error:", err.message);
});How to use the fields in production
Localization and formatting:
- Country and region codes: countryCode and region are concise for routing and rules engines.
- Timezone: Use the IANA string directly with your time libraries to render local timestamps on receipts or dashboards.
- Latitude/longitude: Keep as floating point values in decimal degrees for mapping and proximity checks.
Risk and access control:
- Proxy/VPN detection: security.is_proxy and security.is_vpn are booleans suited for session hardening or 2FA prompts.
- Cloud provider detection: security.is_cloud_provider can inform rate limiting on signups or sensitive endpoints.
- Network attribution: isp, org, and as help detect anomalies such as sudden changes in user network profile.
Caching and request strategy
IP geolocation changes slowly compared to user requests, but security flags can be more dynamic. Common patterns:
- Cache stable fields (country, regionName, city, timezone, lat, lon) for longer periods.
- Refresh security flags more often to reflect proxy/VPN and cloud-provider changes.
- Store the raw JSON for traceability, and also log a normalized subset for analytics.
If you serve global traffic, place lookups near your edge. Keep your Accept and Authorization headers consistent across clients and services to reduce variance in middleware handling.
Input validation and fallbacks
Always sanitize user-provided IPs before calling your geolocation layer. If the IP is missing or invalid, skip the lookup and fall back to default content or a neutral timezone. Use the status field to verify success before using the response. If status is not "success", avoid partial logic based on assumptions.
Handling response variability
Network metadata and security indicators can evolve. Use defensive parsing for nested fields like security. Don’t persist assumptions about a user’s flags beyond your chosen refresh window, and be prepared for boolean flips at any time. Where you derive risk scores internally, keep the raw flags and your decisioning separate to simplify audits.
Deploying safely
- Secrets management: keep YOUR_API_KEY in server-side configuration or secrets vaults, never in public repositories.
- Timeouts and retries: set client timeouts and bounded retries around the GET call to avoid cascading timeouts.
- Observability: log request IDs and the status field to identify upstream issues early.
- Back-pressure: if you experience spikes, queue non-critical lookups and serve cached results for a short period.
Reference links
Testing strategy with the fixture
Use the documented fixture IP 148.105.12.120 to validate your field mapping and ensure your code handles success responses correctly. Because live flags can change, test your logic on boolean transitions for security fields without assuming they are constant. Record a few complete JSON samples in your test suite to catch regressions when you alter parsers or storage schemas.
Data storage model suggestions
For typical applications, a denormalized record per IP is sufficient. Recommended fields to store:
- ip, countryCode, region, city, timezone
- lat, lon
- isp, org, as
- security flags
- inEU, continentCode
- status for sanity checks
Track created_at and refreshed_at timestamps to manage TTLs for security vs. location data. Keep an index on ip for quick lookups. If you implement user session enrichment, also store the last-seen IP metadata next to the session ID for analytics and anomaly detection.
Edge and server placement
If your stack includes an edge runtime or CDN worker, consider doing the lookup at the edge and passing only normalized fields to your origin. For server-only deployments, place the call in a middleware layer that runs before routing to features depending on geolocation and security decisions.
Common pitfalls to avoid
- Skipping the status check: always ensure status is "success" before consuming fields.
- Assuming immutable security flags: cache these for a shorter period than static location fields.
- Hard-coding timezone conversions: always rely on the timezone value returned by the API.
- Leaking keys in clients: send requests from your server or use server-side proxies to protect YOUR_API_KEY.
Frequently asked questions
How do I authenticate?
Send Authorization: Bearer YOUR_API_KEY and Accept: application/json with each request to /api/ip.
Is there a free trial?
Yes. The trial is 7 days or 50 requests.
Can the proxy/VPN or cloud-provider flags change?
Yes. Live flags can change. Cache these fields for shorter intervals and refresh them periodically.
Where can I explore the API?
Use the MCP endpoint for API access patterns, and consult the Documentation for endpoint details.
What endpoint and parameters should I call?
Call GET /api/ip with the ip query parameter. Ensure you set the Authorization header and request JSON with the Accept header.
Get started
Register for an API key, run the cURL example against /api/ip with the fixture IP, and wire up the JavaScript sample to parse location, network, and security fields. When you’re ready, move the call to your edge or server middleware and add caching tuned to your use case. Start here: Register.