ASN API

You need to resolve ASN information for an IP address and wire it into geolocation and risk decisions without guessing at undocumented fields or endpoints. By the end of this guide, you will be able to query the ASN and related metadata for a specific IP with a single request, parse the response reliably, and ship a production-ready integration using ipXapi’s /api/ip endpoint.

What you get from an ASN lookup

An Autonomous System Number (ASN) identifies the network that announces routes for an IP address. With one lookup, you can tie an IP to an as string (the ASN with a human-readable label), plus the provider (isp and org), location fields, and a concise set of security indicators. This supports:

• Risk controls: gate traffic differently for consumer ISPs vs. cloud providers using security.is_cloud_provider.
• Routing and compliance: steer users based on countryCode, region, and timezone.
• Analytics: group activity by as, isp, or org without trying to maintain your own mapping.

This article focuses on the single documented endpoint used for ASN and adjacent fields and explains what to extract for production use.

Endpoint and authentication

Endpoint path: /api/ip

Method: GET

Base: https://ipxapi.com

Query parameter: ip (set to the IP you want to look up)

Auth: HTTP header Authorization: Bearer YOUR_API_KEY

Accept: application/json

If you need to test network reachability or status outside your application, you can also reach the hosted control plane at MCP. For API parameter details and field descriptions, see the Documentation.

Quick start: cURL request

Below is the official, copy-pasteable cURL request against the real endpoint using the documented fixture IP:

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

Replace the bearer token value with your actual API key when you run it in your environment. Keep the path and query parameter as shown to reproduce the documented fixture response for 148.105.12.120.

Official response sample

This is the official JSON sample for the fixture IP. Live responses can change, especially for fields that reflect current network or provider states. Use it to validate your parser and field names:

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

What to extract for ASN-driven workflows:

• as: The ASN string and label you will use for network grouping (e.g., “AS14782 MailChimp”).
• isp and org: Provider information to distinguish enterprise networks, consumer ISPs, and cloud.
• security.is_cloud_provider, security.is_proxy, security.is_vpn: Boolean flags that help gate traffic or add friction when needed.
• countryCode, region, city, timezone: Geolocation and local-time context for policy and analytics.
• lat, lon: Coordinates in decimal degrees for map placement and distance checks.
• status and query: Useful for logging whether the request succeeded and what you asked for.

Parse the ASN lookup in code

The following JavaScript example calls the same endpoint and extracts the fields commonly used for ASN and risk decisions. It uses the bearer token format with YOUR_API_KEY.

// Minimal Node.js/Edge-compatible example
// Requires: global fetch (Node 18+, Deno, Bun, or add node-fetch)
const API_URL = 'https://ipxapi.com/api/ip?ip=148.105.12.120';

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) {
// Surface the HTTP status to logs/metrics for alerting
const text = await res.text().catch(() => '');
throw new Error(`ipXapi lookup failed (${res.status} ${res.statusText}): ${text}`);
}

const data = await res.json();

// Expect data.status === 'success' for a good match.
// Live values can differ from the fixture; never hard-code booleans.
const result = {
ip: data.query,
as: data.as, // e.g., 'AS14782 MailChimp'
isp: data.isp, // e.g., 'MailChimp'
org: data.org, // e.g., 'MailChimp'
countryCode: data.countryCode, // e.g., 'US'
region: data.region, // e.g., 'US-CA'
city: data.city, // e.g., 'Mountain View'
timezone: data.timezone, // e.g., 'America/Los_Angeles'
lat: data.lat, // number (decimal degrees)
lon: data.lon, // number (decimal degrees)
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
lookupIp('148.105.12.120')
.then(info => {
// Route decisions based on ASN and security
if (info.security.isCloudProvider) {
console.log('Cloud-origin traffic - consider extra verification.');
}
console.log(`ASN: ${info.as} | ISP: ${info.isp} | Org: ${info.org}`);
console.log(`Geo: ${info.city}, ${info.region}, ${info.countryCode} | TZ: ${info.timezone}`);
})
.catch(err => {
console.error(err);
});

How to interpret fields for policy and routing

Start with as to group traffic by network ownership. Keep in mind that an ASN often spans many prefixes and geographies, so combine it with countryCode or region if you need country-specific gates. For content and legal routing, the timezone string (IANA format) provides the local-time context needed for scheduled features and audits.

The security object carries boolean flags you can turn into immediate controls, such as additional verification when is_cloud_provider is true, or higher friction for new session creation from ranges where is_proxy is true. Because these values can change, always check them per request or cache them for a short period with an expiration strategy that suits your risk posture.

Location fields (country, countryCode, region, regionName, city) work with lat/lon to inform maps, distance calculations (e.g., between last known user location and current request), or geo-based access controls. If you compute distances, remember coordinates are in decimal degrees; use a great-circle or haversine calculation for meters or kilometers.

Production details that save time

• Transport and headers: Always send Accept: application/json and a valid Authorization: Bearer YOUR_API_KEY. Treat non-2xx as errors and log the body text for diagnostics.
• Caching: Cache responses for a moderate TTL to reduce latency and cost, but don’t assume static values. Security flags, ownership, and even geolocation can change.
• Timezones: timezone is an IANA name (e.g., “America/Los_Angeles”). Use a library that understands IANA zones for conversions and scheduling.
• Numerics: lat and lon are floats (decimal degrees). Store them as numbers and format only on display.
• Booleans: Do not hard-code any of the security booleans. Evaluate them on each lookup or after cache refresh.
• Error handling: Expect occasional network failures and timeouts. Implement retries with backoff for idempotent GETs. Log status and the requested IP (query) for observability.
• Input validation: Only send routable public IPs. If your upstream can emit private or reserved ranges, filter them out before calling the API.
• Throughput planning: If you expect high volume, implement per-process connection reuse and response caching. For concurrency strategies and any rate considerations, consult the Documentation.
• Data freshness: If your logic depends on up-to-the-minute security posture, shorten cache TTLs and verify that you re-check values like is_proxy and is_vpn frequently.
• Observability: Emit structured logs with as, isp, org, countryCode, and security flags so you can trend changes and quickly tune policies.

End-to-end example workflow

Below is a practical flow you can adapt to your service when making an allow/step-up/deny decision per request or session:

1. Receive request with client IP (from your proxy or load balancer’s canonical header).
2. Normalize the IP (e.g., strip port, validate format, ensure public).
3. Check your cache. If missing or expired, request /api/ip?ip=the.address with Authorization Bearer.
4. Parse status. If not success, apply a safe default (e.g., step-up auth) and log.
5. Extract:
   • Network identity: as, isp, org.
   • Geo: countryCode, region, city, timezone, lat, lon.
   • Security: is_proxy, is_vpn, is_cloud_provider.
6. Evaluate policies:
   • If is_cloud_provider is true, require stronger verification for signups or high-value actions.
   • Block or throttle known proxies (is_proxy) where policy requires.
   • Apply geo controls and preview UI in local timezone.
   • Group metrics and rate limits by as for visibility into network-level behavior.
7. Cache the parsed result with a TTL. Persist key attributes needed for audits and analytics.

Pricing, trial, and getting access

The Basic plan is $29.99 per month. A trial is available for 7 days or 50 requests. You can create an account and get your API key here: Register. For the full parameter and field reference, visit the Documentation. For control-plane access, see MCP.

FAQ

Does the API return an ASN object or a string?
The ASN is provided as a string in the as field (for example, “AS14782 MailChimp”). Parse it as text; do not assume nested structure.

How do I authenticate requests?
Send an HTTP header Authorization: Bearer YOUR_API_KEY and Accept: application/json with each GET to /api/ip. If you see a non-2xx response, log it and retry with backoff.

Can I look up multiple IPs in one request?
This guide covers the documented single-IP query using /api/ip?ip=.... To process many IPs, loop through your list and apply connection reuse and caching to minimize latency and calls.

Are the security flags stable?
They are live indicators and can change. Never hard-code expected values. Re-check them per request or after your cache TTL elapses.

What happens if I omit the ip parameter?
This article documents usage with an explicit ip parameter. For other behaviors, consult the Documentation and send explicit IPs in production to avoid ambiguity.

Ship your ASN-driven routing and risk checks with a single endpoint. Create your account, get an API key, and start calling /api/ip in minutes: Register. Then keep the field reference handy while you build: Documentation.