How to Do an ASN WHOIS Lookup

An ASN WHOIS lookup tells you which organization operates a network; the registered owner of an autonomous system, the registry that allocated it, the block the number came from, and who to contact about abuse coming out of it. This tutorial shows you how to run one with the WhoisFreaks ASN WHOIS API, how to read every field it returns, and how to get from an IP address to the AS number in the first place.

You'll need an API key. If you don't have one yet, sign up and grab your key first; new accounts include 500 free credits, no card required.

What an ASN is, and What the Lookup Answers

An Autonomous System is a collection of IP networks run under one clearly defined routing policy, and an Autonomous System Number (ASN) is the identifier that system announces to the rest of the internet over BGP. Every network that speaks BGP; every ISP, hosting company, cloud provider and large enterprise; has at least one. When traffic reaches you from 142.250.0.0/15, the ASN is what tells you the network is Google's rather than a random rented box.

That makes an ASN lookup a different question from an IP WHOIS lookup, and the distinction matters when you're deciding which call to make:

Note the split, because it is the single most common wrong turn here: IP WHOIS does not return an AS number. Its documented response is ip_address, query_time, whois_server, inet_nums, organization, technical_contacts, abuse_contacts and whois_raw_response; a registry allocation record with contactable humans on it, and nothing about BGP. The network.asn object lives on the IP Geolocation and IP Security endpoints. So geolocation is what turns an address into an AS number, and ASN WHOIS is what turns that number into an accountable operator with a mailing address and a contact handle. IP WHOIS is the third call you make when you want the allocation record and the abuse address for that one address.

The three workflows this comes up in most:

• Attributing an IP range to an operator: A log line gives you an address. The AS number gives you the organisation that announced it, which is who actually controls the range; not necessarily whoever the reverse DNS suggests.
• Threat intel enrichment: Tagging every indicator with its AS number lets you cluster events by network rather than by address, so a hundred rotating IPs inside one hosting provider collapse into a single actor signal.
• Identifying the hosting provider behind abuse: The abuse_contacts handle on the organisation record is the address a takedown or abuse report actually goes to.

Step 1: Get Your API Key

Sign in to the WhoisFreaks dashboard and open API Keys. Copy your primary key; it's the only credential the ASN WHOIS API needs, and it travels as the apiKey query parameter. No headers, no OAuth flow, no request body.

Step 2: Run Your First ASN Lookup

Send a GET request to the asn-whois endpoint with the AS number you want:

curl "https://api.whoisfreaks.com/v1.0/asn-whois?apiKey=API_KEY&asn=as56554"

Replace API_KEY with your key and as56554 with the AS number you're checking. The as prefix is optional; the documentation states the parameter takes "the ASN number with or without 'as'", so asn=as1009 and asn=1009 are both accepted. The samples use the prefixed form, and staying consistent with it is the safer habit when you're building request strings from mixed-source data.

The parameters this endpoint accepts:

That's the whole surface. There is no bulk variant of this endpoint and no per-record type selector; one AS number per call, full record returned.

If you just want to eyeball one number before you write any code, the ASN WHOIS lookup tool runs the same query in the browser.

Step 3: Read the Response

A successful lookup returns 200 with the AS registration record, trimmed here to the fields that carry the meaning:

{
  "status": true,
  "as_number": "AS56554",
  "query_time": "2024-02-01 08:28:26",
  "whois_server": "whois.ripe.net",
  "as_blocks": [
    {
      "as_block": "AS56444; AS57146",
      "description": [
        "RIPE NCC ASN block"
      ],
      "mnt_by": [
        "RIPE-NCC-HM-MNT"
      ],
      "date_created": "2023-08-23",
      "date_updated": "2023-08-23",
      "source": "RIPE"
    }
  ],
  "aut_nums": [
    {
      "aut_num": "AS56554",
      "as_name": "IETF-MEETING",
      "description": [
        "IETF Meeting Network"
      ],
      "status": "ASSIGNED",
      "import": [
        "from AS-ANY accept ANY"
      ],
      "export": [
        "to AS-ANY announce ANY"
      ],
      "organization": "ORG-IS136-RIPE",
      "sponsoring_organization": "ORG-NIE1-RIPE",
      "admin_contacts": [
        "IED11-RIPE"
      ],
      "tech_contacts": [
        "IETF-RIPE"
      ],
      "date_created": "2011-03-16",
      "date_updated": "2019-03-26",
      "source": "RIPE"
    }
  ],
  "organization": {
    "handle": "ORG-IS136-RIPE",
    "name": "Internet Society",
    "type": "OTHER",
    "street": "Galerie Jean-malbuisson",
    "city": "Geneva",
    "zip_code": "CH-1204",
    "country": [
      "CH"
    ],
    "abuse_contacts": [
      "AR28097-RIPE"
    ],
    "date_created": "2010-11-09",
    "date_updated": "2022-12-01",
    "source": "RIPE"
  },
  "administrative_contacts": [
    {
      "handle": "IED11-RIPE",
      "name": "IETF Executive Director"
    }
  ],
  "technical_contacts": [
    {
      "handle": "IETF-RIPE",
      "name": "IETF NOC"
    }
  ],
  "whois_raw_response": "#########################################"
}

What each top-level field tells you:

Three details in there are worth pointing out because they're where most integrations go wrong.

as_blocks and aut_nums are arrays, not objects. Even when there's exactly one of each; which is the normal case; you have to index into them. Write aut_nums[0].as_name, not aut_nums.as_name.

description, country, mnt_by, import, export and the contact lists are arrays of strings. Registry records are multi-line by nature; a single-line value still arrives as a one-element array. Join them rather than assuming a scalar.

Contacts are handles, not people. organization.abuse_contacts gives you AR28097-RIPE; a registry handle. The postal address you can act on sits on the organization object itself, and the named contacts are expanded in administrative_contacts and technical_contacts.

Step 4: Start From an IP Instead of an AS Number

Most investigations begin with an address, not a number. The endpoint that maps an IP to an AS number is IP Geolocation, not IP WHOIS:

curl --location --request GET 'https://api.whoisfreaks.com/v1.0/geolocation?apiKey=API_KEY&ip=8.8.8.8'

The response carries a network.asn block:

{
  "network": {
    "asn": {
      "as_number": "AS15169",
      "organization": "Google LLC",
      "country": "US",
      "asn_name": "GOOGLE",
      "type": "BUSINESS",
      "domain": "google.com",
      "date_allocated": "2000-03-30",
      "allocation_status": "",
      "num_of_ipv4_routes": "1068",
      "num_of_ipv6_routes": "152",
      "rir": "ARIN"
    },
    "connection_type": "",
    "company": {
      "name": "Google LLC",
      "type": "HOSTING",
      "domain": "google.com"
    }
  }
}

Take as_number from there and feed it straight into the ASN endpoint:

curl "https://api.whoisfreaks.com/v1.0/asn-whois?apiKey=API_KEY&asn=AS15169"

If you are already enriching indicators for threat work, the IP Security endpoint gets you the same AS number alongside the VPN, proxy, Tor and known-attacker flags, so you do not need a separate geolocation call:

curl --location --request GET 'https://api.whoisfreaks.com/v1.0/security?apiKey=API_KEY&ip=8.8.8.8'

One difference to code around: on the security response the ASN object sits at the top level as asn, not under network, and it carries a smaller set of fields; as_number, organization, country, type, domain, date_allocated and rir, with no asn_name and no route counts. Read asn.as_number there and network.asn.as_number on geolocation.

Which call answers which question:

So the full pivot is two calls and two credits: geolocation to get the number, ASN WHOIS to get the operator. Add IP WHOIS as a third call when the address itself is what you need to report on; it returns the inet_nums allocation for that address and an abuse_contacts entry with a real email and phone number, which is a narrower, more actionable target than the AS-level abuse handle.

Step 5: Handle the Responses That Aren't a Clean 200

Every failure comes back in the same JSON envelope; timestamp, status, error, message, path; so, one error handler covers all of them. These are the ones to branch on:

Two facts make error handling cheaper than you'd expect. 4xx responses do not consume credits, so a bad AS number in a large batch costs you nothing but time. And the free tier gives you 500 credits at 10 requests per minute on live endpoints (5/min for bulk, 1/min for reverse and historical), which is ample for building and testing this integration.

To pace a loop properly, read the rate-limit headers on every response rather than guessing:

• x-ratelimit-allowed-requests: your ceiling for this endpoint category
• x-ratelimit-remaining-requests: what's left in the current window
• x-ratelimit-remaining-time: time until the window resets, in nanoseconds

Limits are enforced per endpoint category; live, bulk, historical/reverse; not as one global pool, so saturating a bulk endpoint doesn't throttle your ASN lookups. Read the rate limiting documentation.

Summary

One request turns a number announced in a routing table into a named organization with a postal address and an abuse contact. Plans and daily snapshot options are on the ASN WHOIS API product page.

Frequently Asked Questions

What is an ASN lookup?

A query against registry WHOIS data for an Autonomous System Number, the identifier a network announces over BGP. It returns the registered organisation, the allocation block, the status, and the admin, technical and abuse contacts. The WhoisFreaks ASN WHOIS API queries the authoritative registry and returns the record as JSON or XML.

How do I look up an ASN?

GET https://api.whoisfreaks.com/v1.0/asn-whois with your apiKey and asn parameter, e.g. asn=as56554. No headers or body needed, so one cURL command does it. JSON by default; add format=XML for XML.

Do I need the "as" prefix?

No. The asn parameter accepts the number with or without it, so asn=as1009 and asn=1009 both work. Normalising your inputs to one style is still worth doing.

ASN lookup vs. IP WHOIS lookup?

IP WHOIS answers questions about a single address: its allocation block, the assigned organisation, and who to contact about abuse. It returns inet_nums, organization, technical_contacts and abuse_contacts, but no AS number. An ASN lookup returns the registry record for the whole network. To get from an address to an AS number, use IP Geolocation or IP Security, where network.asn lives.

How do I find the ASN for an IP address?

Call IP Geolocation and read network.asn.as_number, or IP Security and read asn.as_number from the top level. The value comes back as AS15169 and passes straight to the ASN WHOIS endpoint. Geolocation also returns asn_name, the RIR and route counts, which is often enough on its own.

Why a 206 instead of a 200?

Partial content: the record was retrieved but not every section came back. as_number, as_blocks and aut_nums are present; organization and the contact sections may not be. Treat it as success with missing optional fields, and check organization exists before dereferencing it.

Does a failed lookup cost credits?

No. 4xx responses consume nothing, so invalid AS numbers, bad keys and throttled requests are free. Still pace your requests rather than relying on 429s.

How many credits does a lookup cost?

One credit per successful query, per the credit usage documentation. IP WHOIS, Geolocation and Security are 1 each, so the IP-to-operator pivot (geolocation, then ASN WHOIS) costs two. New accounts get 500 free credits, no card required.