IP Geolocation API: Official Fixture as JSON
You're building a feature that needs accurate IP geolocation to localize content, comply with regional rules, or route requests intelligently. By the end of this guide, you'll know exactly how to call the ipXapi Geolocation endpoint, authenticate with a Bearer token, parse the official JSON fields, and integrate the data into your application with a straightforward caching and deployment approach.
What you can build with the ipXapi Geolocation response
The IP Geolocation lookup gives you the country, region, city, postal code, coordinates, timezone, and network ownership signals for an IP address. These fields enable practical use cases such as:
- Localizing UI defaults (language, currency display, timezone) before profile settings load.
- Compliance gates (per-country feature flags or consent flows).
- Traffic routing and latency improvements using regional context.
- Fraud and abuse heuristics (e.g., comparing declared user region to originating IP region, or spotting cloud-provider traffic).
This article focuses exclusively on the ipXapi Geolocation lookup and uses only the official path, documented fixture IP, and response format provided below.
Endpoint overview: IP Geolocation lookup
The Geolocation endpoint resolves an IP into geographic and network attributes.
- Lookup: IP Geolocation
- Path:
/api/ip - Base domain:
https://ipxapi.com - Authentication:
Authorization: Bearer YOUR_KEY - Query parameter:
ip(the IPv4 or IPv6 address to look up)
There is also an MCP base at MCP. This post uses the primary host shown in the official curl example for clarity.
Key setup notes:
- Use a Bearer token: include
Authorization: Bearer YOUR_KEYon every request. - Accept JSON: send
Accept: application/jsonso the server returns a JSON body. - Environment separation: keep your key in server-side storage or secure environment variables; avoid embedding it in public client code.
Important: The live response flags and field values may change over time. The official fixture below is for illustration and testing; do not assume it reflects the current properties of the IP or your own environment.
Quickstart: Run the official curl example
Run the following request to see a valid geolocation response using the documented fixture IP address. Replace YOUR_KEY with your real token before executing.
curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"
When successful, you will receive a JSON payload with the fields shown in the official product fixture:
{"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}}
How to read this response:
status: String indicating request success.countryandcountryCode: Human-readable name and a short code (e.g.,US).regionandregionName: Code-style region plus readable region name.cityandzip: City and postal code, if available.latandlon: Coordinates in decimal degrees (WGS84).timezone: IANA timezone identifier (e.g.,America/Los_Angeles).isp,org, andas: Network ownership and autonomous system descriptor.query: The IP you looked up, echoed for reference.inEUandcontinentCode: Regional classification flags.security: High-level network indicators such asis_proxy,is_vpn, andis_cloud_provider.
Note: Live flags can change. Do not treat this fixture as the reader’s IP, nor assume these fields will remain fixed for the documented IP.
Using the IP Geolocation in code
The following JavaScript example calls the same endpoint you saw in curl and extracts the fields most applications use. Insert your Bearer token where indicated. For production, keep your key server-side and proxy requests if you must call from a browser environment.
async function lookupIpGeolocation() {
const endpoint = 'https://ipxapi.com/api/ip?ip=148.105.12.120';
const res = await fetch(endpoint, {
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_KEY'
}
});
if (!res.ok) {
// Handle non-2xx responses gracefully
const text = await res.text();
throw new Error('ipXapi error ' + res.status + ': ' + text);
}
const data = await res.json();
// Pull the fields you actually need
const geo = {
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,
as: data.as,
inEU: data.inEU,
continentCode: data.continentCode,
security: data.security
};
// Example usage patterns:
// - Convert times using the IANA timezone string
// - Toggle features based on countryCode or inEU
// - Adjust map camera or coordinates using lat/lon
console.log('Geolocation:', geo);
return geo;
}
// Execute only in a secure environment where YOUR_KEY is protected
lookupIpGeolocation().catch(err => {
console.error(err);
});
Practical implementation notes:
- Timezone: The
timezoneis an IANA identifier; in most languages you can pass it directly to a timezone-aware library (e.g., for formatting dates on the server). - Coordinates:
latandlonare in decimal degrees. Map libraries typically accept these without conversion. - Security flags: Treat
securitybooleans as signal, not as a sole decision point. They are useful inputs to risk-scoring or routing decisions.
Mapping response fields to typical features
If you are planning your integration, here is how the returned fields commonly map to real-world features:
- Localization defaults: Use
countryCodeto set default country pickers andtimezonefor local time displays before profile sync. - Compliance and gating: Use
countryCodeorinEUto select flows (e.g., consent banners, restricted features). Always persist the displayed rationale for auditability. - Traffic management: If your infrastructure spans regions, map
region/regionNameto nearby edges or data centers, while observing your own routing policies. - Content relevance: Filter or weight content by
country,regionName, orcityto improve initial discovery and conversions. - Abuse heuristics: Combine
as,org, andsecurity.is_cloud_providerwhen adjusting rate limits or sign-up friction.
Caching, consistency, and operational details
To keep your integration reliable and cost-efficient, incorporate the following practices:
- Cache geolocation per IP for a limited time consistent with your freshness needs. IP geolocation does not typically change minute-to-minute, so even modest caching can reduce latency and request volume.
- Handle variability: Values for a given IP may change. Design your code to accept field changes without breaking (e.g., new region codes, updates to
securityflags). - Error handling: On non-2xx responses, back off and log the body text. Avoid tight retry loops; space out retries to protect your systems and the API.
- Timeouts: Define caller-side timeouts so a slow network does not block your request pipeline. Fall back to a previous cached value if appropriate.
- Precision:
lat/lonuse decimal degrees. If you rasterize to a grid or cluster, keep precision sufficient for your use-case. - Normalization: Persist both
countryandcountryCodeso that you can render names while filtering by codes.
Environments, testing, and the documented fixture
Local development and CI test runs benefit from a deterministic IP. Use the documented fixture IP when exercising your parsing logic or validating mapping logic in test environments:
- Fixture IP:
148.105.12.120 - Endpoint path:
/api/ip - Host:
https://ipxapi.com
You can inspect or extend your integration against the managed control plane at MCP, and refer to the API reference for request/response semantics in the Documentation.
Testing tips:
- Mocking: Keep a checked-in JSON sample mirroring the official fixture. Your tests should verify field presence and types (string, number, boolean, nested object) rather than exact values.
- Schema drift: When deploying, alert on unexpected fields or missing expected fields. Parse with defensive defaults to avoid breaking changes in your code paths.
- Data privacy: If you log geolocation responses, ensure the logs respect your data retention policies and any jurisdictional requirements.
Production rollout and security
Protect your API key and avoid exposing it in client-side code. Recommended strategies include:
- Server-side calls: Make the request from your backend, then pass the minimal fields your UI needs.
- Token storage: Use environment variables or your secrets manager. Rotate credentials on a schedule consistent with your security policies.
- Network controls: Restrict egress from your servers to known API hosts as part of your outbound firewall policy.
Operational practices:
- Observability: Record high-level metrics (request count, latency, error rate). Include region/country distributions if helpful for capacity planning.
- Backoff: If you experience throttling or transient errors, implement exponential backoff and fall back to cached data where reasonable.
- Idempotency at the edge: Since lookups are read-only, simple retries are safe, but keep retry budgets conservative.
Practical feature patterns with the returned fields
Here are concrete patterns for the data you receive:
- Default time localization: Map the IANA
timezonedirectly into your date formatting library on the server. This yields correct DST handling without manual tables. - Country-driven UX: Gate flags by
countryCodeto enable/disable features at the controller or middleware level before controller logic runs. - Regional routing: If
regionis populated, prefer the region’s nearest infrastructure node. Otherwise, fall back to country-to-region mapping in your config. - Fraud checks: When
security.is_cloud_provider === true, tighten rate limits or require additional verification for sensitive flows (e.g., sign-ups or payment updates). - Analytics sanity: Store
queryalongside derived fields so you can re-verify or re-enrich if your requirements evolve.
Trial, pricing, and when to scale
You can start quickly with the trial period and move to a paid plan as your volume grows:
- Trial: 7 days or 50 requests (whichever comes first).
- Basic: $29.99/month.
As you approach your usage threshold, plan caching and request batching where applicable to reduce redundant lookups. For details on endpoints and integration specifics, visit the Documentation.
FAQ
Is the documented fixture IP my current IP?
No. The documented fixture is for demonstration and testing only. Do not assume it represents your network or current environment.
Can I call the endpoint without the Authorization header?
No. Use the Bearer token header: Authorization: Bearer YOUR_KEY for every request.
How often should I cache results?
That depends on your freshness requirements. IP geolocation usually does not change rapidly, so caching per IP for a short, policy-appropriate period can reduce latency and cost. Choose a duration aligned to your product’s needs and update cadence.
Which timezone format is returned?
The timezone field uses IANA names (e.g., America/Los_Angeles). Most time libraries support these identifiers directly.
Do the security flags guarantee a proxy or VPN?
No. security flags are valuable signals but should be combined with your own heuristics and policies.
Get started
Spin up your IP Geolocation integration now. Create an account, retrieve your Bearer token, and run the curl shown above. You can register here: Register. Then work through the endpoint details in the Documentation and keep MCP handy for environment and operational visibility.
