IP Geolocation API
You need accurate IP geolocation plus quick proxy/VPN checks to personalize content, block abuse, or meet compliance, and you don’t want to sift through ambiguous data. By the end of this guide, you will be able to query ipXapi’s IP Geolocation endpoint, parse location, ASN, and security fields, and ship a production-ready integration with caching, testing, and rollout notes.
What you can build with the IP Geolocation endpoint
The IP Geolocation endpoint returns country, region, city, coordinates, time zone, and network attributes for an IPv4 address. It also includes security flags for proxy/VPN detection and a string field with ASN details. Typical use cases include:
- Geotargeting content and localizing UI by country, region, or time zone.
- Fraud and abuse screening with proxy/VPN detection.
- Enforcing licensing or compliance rules by country code.
- Analytics and segmentation by continent or ISP/organization.
Everything below references the same, single endpoint and documented fixture IP so you can copy/paste and verify your setup quickly.
Endpoint, path, and authentication
The IP Geolocation lookup is a simple GET request:
- HTTP method: GET
- Path: /api/ip
- Query parameter: ip
- Auth: Authorization: Bearer YOUR_KEY
Requests must include an Accept header for JSON and a Bearer token in the Authorization header. Replace only the token with your actual credential; keep the rest of the request unchanged. Use the fixture IP below to validate your environment before wiring your application logic.
Make your first request
Use the official cURL below to test your setup end to end. It targets the documented fixture IP 148.105.12.120 and uses Bearer authentication.
curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"Official sample response
Here is the official product-fixture JSON for the same IP. Live datasets can change, so use this for tooling tests and contract checks. Do not treat it as your user’s IP or as static, real-time data.
{
"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 you will likely reference:
- country, countryCode: Jurisdictional checks and localized content.
- region, regionName, city, zip: Finer-grained geotargeting.
- lat, lon: Coordinates (decimal degrees) for mapping and distance rules.
- timezone: Canonical Olson ID (e.g., America/Los_Angeles) for time conversions.
- isp, org: Network owner insights for analytics or trust signals.
- as: ASN string, includes the ASN and name in one value.
- security.is_proxy, security.is_vpn: Boolean indicators for proxy/VPN detection.
- security.is_cloud_provider: Boolean to help treat cloud-hosted traffic differently.
Minimal implementation: fetch and parse the fields that matter
The snippet below demonstrates a compact Python integration that calls the same endpoint, checks the security flags, and extracts a few location attributes you might use for routing and logging. You can adapt this logic to your framework or job runner.
import json
import sys
import urllib.request
API_URL = "https://ipxapi.com/api/ip?ip=148.105.12.120"
headers = {
"Accept": "application/json",
"Authorization": "Bearer YOUR_KEY"
}
req = urllib.request.Request(API_URL, headers=headers)
with urllib.request.urlopen(req) as resp:
data = json.loads(resp.read().decode("utf-8"))
# Basic guards
if data.get("status") != "success":
sys.exit("Lookup did not succeed")
# Extract commonly used fields
country_code = data.get("countryCode")
region = data.get("region")
city = data.get("city")
timezone = data.get("timezone")
as_string = data.get("as")
security = data.get("security", {})
# Security checks
is_proxy = security.get("is_proxy", False)
is_vpn = security.get("is_vpn", False)
is_cloud = security.get("is_cloud_provider", False)
print("CC:", country_code, "Region:", region, "City:", city, "TZ:", timezone)
print("ASN:", as_string)
print("Proxy:", is_proxy, "VPN:", is_vpn, "Cloud:", is_cloud)Interpreting geolocation and security signals
When implementing policy or personalization based on IP metadata, keep your logic explicit and reversible. Consider:
- Security flags: Treat is_proxy and is_vpn as separate signals. Some traffic may be proxied for benign reasons, so log and monitor before enforcing blocks.
- Cloud provider: is_cloud_provider can indicate data-center or server-originated traffic. You can de-prioritize personalization and increase challenge steps for such traffic.
- ASN string: The as field is a single string; if you need the numeric ASN, parse the leading number if present in the value. Keep your parser resilient to formatting variations.
- Time zone: timezone is provided as an Olson zone. Use it for correct local time formatting and scheduling. Avoid relying on city/region alone for time conversions.
- Coordinates: lat and lon are decimal degrees. If you implement geo-fencing or distance rules, ensure you clamp inputs and handle nulls gracefully.
Production notes: performance, caching, and stability
To keep response times stable and costs predictable, add these safeguards:
- Client caching: Cache by IP for a short TTL when your risk model allows it. Many users maintain the same IP for minutes to hours; adjust TTL to your sensitivity.
- Server-side memoization: If your app makes multiple lookups for the same IP within a request, memoize to avoid duplicate calls.
- Cold-start readiness: Pre-warm your HTTP client and connection pool if your runtime supports it.
- Backoff and retries: Implement bounded retries on transient network errors. Avoid retrying on clear client mistakes (e.g., missing auth).
- Observability: Log query (anonymized or truncated as needed), status, and parsed flags. Maintain a small allow/deny list for known test IPs in non-production environments.
Testing, tooling, and MCP
Keep your integration reproducible. Use the documented fixture IP 148.105.12.120 throughout local and CI tests to verify contract stability, mapping, and your parsing logic. Avoid conflating test results with live user traffic.
If you maintain internal tools or scripts, the Management Control Plane is available here: MCP. Use it to assist operational workflows around the same geolocation functionality you integrate via API.
Security and privacy considerations
IP data can be sensitive. Ensure your usage aligns with your privacy policy and applicable regulations. Store only what you need, scope access appropriately, and encrypt logs at rest. For client-facing experiences, keep fallbacks when fields are unavailable and avoid exposing raw network attributes in the UI unless necessary.
Rollout checklist
- Connectivity: Verify cURL succeeds in your runtime environment with Authorization: Bearer YOUR_KEY replaced by your real key.
- Parsing: Unit test your field extraction for countryCode, timezone, and the security flags, and ensure your code tolerates missing fields.
- Feature flags: Gate policy decisions (e.g., block vs. challenge) with kill switches to adjust thresholds without redeploying.
- Metrics: Track lookup count, cache hit ratio, and decision outcomes to tune TTLs and rules.
- Documentation: Keep a short internal runbook that includes the endpoint path (/api/ip), required headers, and the example fixture IP.
Pricing, trial, and where to go next
The Basic plan is $29.99/mo. The trial is 7 days or 50 requests. To explore fields, limitations, and integration options in more depth, review the product documentation and then register when you are ready to ship.
FAQ
What authentication does the IP Geolocation endpoint use?
Use an Authorization header with a Bearer token. The header format is Authorization: Bearer YOUR_KEY. Include Accept: application/json in the request.
Which endpoint and parameters should I call?
Send a GET request to /api/ip with the ip query parameter, for example: https://ipxapi.com/api/ip?ip=148.105.12.120.
How do I detect proxies or VPNs?
Inspect the security object in the response and read security.is_proxy and security.is_vpn booleans. You can also check security.is_cloud_provider to identify data-center originated traffic.
Can I rely on city or region for time calculations?
Use the timezone field instead. It is returned as an Olson time zone string (e.g., America/Los_Angeles) and is the correct basis for local time conversions.
What is the fastest way to validate my integration?
Run the official cURL with your Bearer token, confirm a status of success, and write a small script that parses countryCode, timezone, and the security flags using the fixture IP 148.105.12.120 before moving to live traffic.
Get started
Set your Authorization header, call /api/ip with the IP you want to evaluate, and wire the security and location fields into your routing and policy code. When you are ready to move beyond the fixture and test against live IPs, create your key here: Register.