IP Lookup API

You need to geolocate an IP address, detect VPN/proxy usage, and read ISP/ASN metadata to personalize content, block abuse, or comply with regional rules. By the end of this guide, you’ll be able to call a production IP Lookup endpoint, parse the geolocation and security fields, and ship a minimal integration you can extend safely.

What this IP Lookup covers

The endpoint returns a single, structured record for a given IP that includes:

• Geolocation: country, region, regionName, city, zip, lat, lon, timezone.
• Network and ASN: isp, org, and as (string with ASN and name).
• Jurisdictional flags: inEU and continentCode.
• Security posture: security.is_proxy, security.is_vpn, security.is_cloud_provider.

This is sufficient for common geolocation flows (e.g., routing by country, regional content/legal constraints) as well as abuse checks (e.g., avoid VPN/proxy traffic or apply additional friction).

Endpoint and authentication

Use the following path and documented fixture IP for examples:

• HTTP method: GET
• Path: /api/ip
• Query parameter: ip (IPv4 address)
• Fixture IP for docs and testing: 148.105.12.120
• Auth: Authorization: Bearer YOUR_KEY
• Accept JSON: Accept: application/json

The base domain is ipxapi.com for the public HTTPS API. For machine-to-machine control plane or management tooling, use the MCP endpoint at MCP.

Quickstart: cURL request

Copy and run this request with your key. The query IP is the documented fixture; replace it with your own when integrating.

curl "https://ipxapi.com/api/ip?ip=148.105.12.120" -H "Accept: application/json" -H "Authorization: Bearer YOUR_KEY"

Official JSON response

This is the official product-fixture JSON for the fixture IP. Live flags can change; do not treat this IP as your own or as a constant source of truth beyond this example.

{
"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
}
}

Fields you will typically use:

• country, countryCode, region, regionName, city, zip: for localization and compliance routing.
• lat, lon: for radius rules or nearest-location selection.
• timezone: display local times; offsets derive from this IANA name.
• isp, org, as: network and ASN string for analytics and allow/deny decisions.
• inEU, continentCode: jurisdiction toggles (privacy, consent, tax).
• security.is_proxy, security.is_vpn, security.is_cloud_provider: apply extra friction, MFA, or logging if true.

Minimal client example (JavaScript)

This snippet calls the same endpoint, handles JSON, and extracts the key geolocation and security values. It uses the documented fixture IP for consistency; swap it with your target IP at runtime.

async function lookupIp() {
const url = 'https://ipxapi.com/api/ip?ip=148.105.12.120';
const res = await fetch(url, {
method: 'GET',
headers: {
'Accept': 'application/json',
'Authorization': 'Bearer YOUR_KEY'
}
});

if (!res.ok) {
// Non-2xx: surface status and body for debugging/logging
const text = await res.text();
throw new Error('ipxapi error ' + res.status + ': ' + text);
}

const data = await res.json();

// Read the geolocation subset you actually need
const geo = {
countryCode: data.countryCode,
region: data.region,
city: data.city,
zip: data.zip,
lat: data.lat,
lon: data.lon,
timezone: data.timezone
};

const network = {
isp: data.isp,
org: data.org,
asn: data.as // Contains ASN string with name (e.g., "AS14782 MailChimp")
};

const security = {
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, network, security, raw: data };
}

lookupIp()
.then(({ geo, network, security }) => {
console.log('Geolocation:', geo);
console.log('Network:', network);
console.log('Security:', security);
})
.catch(err => {
console.error(err);
});

Designing your geolocation workflow

Start by deciding what decision you need to make per request. Examples:

• Localization: map countryCode and region to content or prices, and use timezone for localized timestamps.
• Compliance: gate features when inEU is true or when countryCode requires additional consent.
• Abuse controls: if security.is_vpn or security.is_proxy is true, step up authentication or block flows.
• Analytics: enrich events with as, isp, and continentCode for cohort analysis.

Avoid persisting geolocation for long periods. IP-to-location and security states can change. A short cache window balances performance and freshness.

Input validation and error handling

Accept only IPv4/IPv6 string inputs in your edge or backend. If upstream systems can emit malformed IPs, validate before sending to the API to avoid unnecessary requests. When the response is non-2xx or status is not success, return a safe default behavior (e.g., generic locale) and log the event for review.

• Timeouts: set client timeouts appropriate for your SLA; the endpoint returns a single record per request.
• Backoff: implement retries with jitter on transient network errors only; do not retry on deterministic failures (e.g., invalid query IP).
• Observability: record countryCode and security flags for sampled diagnostics to confirm rules behave as expected.

Timezone usage and formatting

The timezone field is an IANA timezone name (e.g., America/Los_Angeles). Use it to derive offsets for display. Avoid hardcoding offsets; daylight saving and regional changes are handled by libraries that use IANA names.

• Server rendering: format times with the IANA timezone from the lookup.
• Client rendering: if you enrich events server-side, pass timezone through your APIs for consistent formatting in UIs.

Security flags integration

The security object provides Boolean flags for proxy, VPN, and cloud-provider hosting. Typical patterns:

• Allow but verify: let users proceed, but require email or phone verification when is_vpn or is_proxy is true.
• Block risky signup: if your policy forbids hosted network origins, reject when is_cloud_provider is true for create-account flows.
• Adaptive rate limits: lower thresholds for IPs with is_proxy or is_vpn set to true.

Apply decisions consistently and log the specific flag that triggered the rule. Keep a review workflow so you can adjust without code changes.

Caching strategy

Since the endpoint is a pure function of the query IP, you can cache responses per IP to reduce latency and cost. A practical approach:

• Key: ipxapi:/api/ip?ip={ip_value}
• TTL: choose a short TTL that aligns with how often you need fresh security flags; live flags can change.
• Invalidation: on security-sensitive operations (auth, payments), consider bypassing cache or using a shorter TTL than for analytics.

If you run at the edge, cache in a POP close to the user. For server-side workloads, a memory cache or a small external KV store is sufficient.

MCP and environments

For centralized configuration or integrations that need managed connectivity, the MCP endpoint is available: MCP. Use it where appropriate in your infrastructure; the data model is the same geolocation category discussed here.

Pricing and trial

A basic plan is available at $29.99/mo. A trial is offered for 7 days or 50 requests. Choose the tier that matches your expected traffic and the freshness requirements for your caching policy.

Production checklist

• Authentication: send Authorization: Bearer YOUR_KEY with every request.
• Input: ensure the ip query parameter is present and valid before calling the API.
• Parsing: read countryCode, region, timezone, as, and security flags you need for decisions.
• Fallbacks: define behavior when the lookup fails (e.g., default locale and stricter fraud rules).
• Caching: set a TTL policy; keep it shorter for decisions impacted by security flags.
• Logging: record minimal fields for audits and to tune rules later (no need to store full payloads indefinitely).

Frequently asked questions

Can I query multiple IPs at once?
This guide covers a single-IP lookup via /api/ip with the ip query parameter. If you need batch behavior, check the Documentation for available options.

What timezone format is returned?
The response includes an IANA timezone string (e.g., America/Los_Angeles). Use standard libraries to compute offsets and DST-aware displays.

How should I treat the ASN?
The as field is a string that includes the ASN and the operator name. Store it as-is for analytics or parse out the numeric portion if you need to join with your own ASN lists.

Are VPN/proxy flags stable?
They can change over time. Cache modestly and refresh on high-sensitivity actions (auth, payments) to keep decisions accurate.

What happens if the IP is private or malformed?
Validate inputs before calling the API. If a request fails, return a safe default and log the error for review rather than blocking the entire flow.

Get started

Register for an API key and implement the single-call lookup you built here, then iterate on caching and decision rules as your traffic grows. Create your account now: Register. For deeper parameter and model notes, see the Documentation.