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_KEY on every request.
• Accept JSON: send Accept: application/json so 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.
• country and countryCode: Human-readable name and a short code (e.g., US).
• region and regionName: Code-style region plus readable region name.
• city and zip: City and postal code, if available.
• lat and lon: Coordinates in decimal degrees (WGS84).
• timezone: IANA timezone identifier (e.g., America/Los_Angeles).
• isp, org, and as: Network ownership and autonomous system descriptor.
• query: The IP you looked up, echoed for reference.
• inEU and continentCode: Regional classification flags.
• security: High-level network indicators such as is_proxy, is_vpn, and is_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 timezone is 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: lat and lon are in decimal degrees. Map libraries typically accept these without conversion.
• Security flags: Treat security booleans 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 countryCode to set default country pickers and timezone for local time displays before profile sync.
• Compliance and gating: Use countryCode or inEU to select flows (e.g., consent banners, restricted features). Always persist the displayed rationale for auditability.
• Traffic management: If your infrastructure spans regions, map region / regionName to nearby edges or data centers, while observing your own routing policies.
• Content relevance: Filter or weight content by country, regionName, or city to improve initial discovery and conversions.
• Abuse heuristics: Combine as, org, and security.is_cloud_provider when 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 security flags).
• 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/lon use decimal degrees. If you rasterize to a grid or cluster, keep precision sufficient for your use-case.
• Normalization: Persist both country and countryCode so 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 timezone directly into your date formatting library on the server. This yields correct DST handling without manual tables.
• Country-driven UX: Gate flags by countryCode to enable/disable features at the controller or middleware level before controller logic runs.
• Regional routing: If region is 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 query alongside 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.