An Autonomous System Number (ASN) is a unique identifier assigned to an autonomous system. ASNs are crucial for the Border Gateway Protocol (BGP), which uses them to identify ASes and determine the best routing paths between them.

Peers are networks or independent ASes that have direct connection with each other to exchange traffic without going through upstream transit provider. Peering is typically established for mutual benefits, meaning that neither party pays the other for the exchange of traffic.

ASN Lookup API Documentation

Q: What is Autonomous System?

An Autonomous System (AS) is a collection of IP networks and routers under the control of a single entity or organization. This entity can be an ISP, a large corporation, or a university. To connect to the internet, every network typically needs to be part of an autonomous system. Each autonomous system operates under a single routing policy.

Q: What is Border Gateway Protocol (BGP)?

BGP is the protocol used to exchange routing information between different autonomous systems on the internet. It announces the reachability of IP address prefixes through specific ASes, enabling data to be routed efficiently. BGP is essential for directing traffic along the best possible path across the internet.

Q: What is routing policy?

The routing policy is a set of rules that asn AS organization follows to decide which routes to advertise (export policy) and which routes to accept (import policy). BGP does not select route on the basis of shortest path only but also considers the routing polices of networks, allowing them to control traffic flow based on their preferences, cost management concerns or agreements.

Q: What are upstreams and downstreams?

Upstreams are higher-tier network providers or ISPs through which an Autonomous System (AS) sends traffic to reach the rest of the internet. Organizations usually pay their upstream providers for global internet connectivity. Downstreams are client networks or smaller ASes that receive connectivity from a given AS. Traffic going towards these customers from the broader internet often goes through the AS.

Q: What data does IP to ASN API provide?

The IP to ASN API provides details such as the ASN associated with a given IP address, the name of the owning organization, country of registration, peering information, upstreams, downstreams, and WHOIS data. This information is valuable for network analysis and monitoring.

Q: Are there free ASN lookup tools available?

Yes, our ASN finder tool offers free lookups with full ASN information. However, for high-volume usage or advanced features, paid plans are available and offer more extensive access.

Q: How frequently is the ASN data updated?

The ASN data is updated daily to maintain accuracy and reflect the latest changes in internet routing.

Q: How can I get ASN Database?

You can access a reliable IP ASN database by creating an account on ipgeolocation.io. Once registered, you'll receive an API key and can access daily or weekly ASN data updates.

ASN Lookup API

The ASN API delivers detailed information about an Autonomous System Number (ASN), including the AS name, organization, country of registration, associated domain, and classification (ISP, hosting provider, education, or business). It also indicates the allocation date and whether the ASN is currently active. It also provides routing insights, including peering relationships, upstream, and downstream connections, helping users understand how ASNs interconnect across the internet.

The API also returns WHOIS data such as the registrant’s organization, contact emails, and abuse reporting addresses. Users can lookup AS numbers or IP addresses (IPv4 or IPv6) to retrieve this information.

Note: For client-side calls to the endpoints mentioned below using the Request Origin (available on paid plans only), the apiKey parameter can be omitted.

Lookup By ASN

Use the endpoint below to retrieve ASN details by specifying an ASN as a query parameter. The API supports both JSON and XML formats. Alternatively, you can specify an IP address to retrieve the details of the ASN associated with that IP.
The URL for this API is https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&asn=1 and it's default JSON response below:

Response

1{
2  "asn": {
3    "as_number": "AS1",
4    "organization": "Level 3 Parent, LLC",
5    "country": "US",
6    "asn_name": "LVLT-1",
7    "type": "BUSINESS",
8    "domain": "level3.com",
9    "date_allocated": "",
10    "allocation_status": "assigned",
11    "num_of_ipv4_routes": "137",
12    "num_of_ipv6_routes": "0",
13    "rir": "ARIN"
14  }
15}

Lookup By IP

To retrieve ASN details using an IP address, use the following endpoint: https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&ip=1.0.0.0. The default response is in JSON format.

Response

1{
2  "ip": "1.0.0.0",
3  "asn": {
4    "as_number": "AS13335",
5    "organization": "Cloudflare, Inc.",
6    "country": "US",
7    "asn_name": "CLOUDFLARENET",
8    "type": "BUSINESS",
9    "domain": "cloudflare.com",
10    "date_allocated": "",
11    "allocation_status": "assigned",
12    "num_of_ipv4_routes": "2343",
13    "num_of_ipv6_routes": "2040",
14    "rir": "ARIN"
15  }
16}

API Parameters

You can use the following parameters to customize the API response based on your requirements.

A. Including Data (include)

This parameter accepts four options:

peers
downstreams
upstreams
routes
whois_response

To include peering data in the response, pass the value peers in the include parameter, as shown below. Also ensure the apiKey is included as a query parameter for authorization.

The response for this parameter appears below.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&asn=1&include=peers'

Response

1{
2  "asn": {
3    "as_number": "AS1",
4    "organization": "Level 3 Parent, LLC",
5    "country": "US",
6    "..."
7    "peers": [
8      {
9        "as_number": "AS25139",
10        "description": "TVCABO - Comunicacoes Multimedia, Lda",
11        "country": "MZ"
12      },
13      {
14        "as_number": "AS7046",
15        "description": "Verizon Business",
16        "country": "US"
17      },
18      "..."
19    ]
20  }
21}

- Include (Combine all objects with ASN details)

To get a complete ASN response, include all values (peers, downstreams, upstreams, routes, whois_response) in the include parameter parameter as shown below. Note that the apiKey must also be passed as a query parameter for authorization. The response for this parameter appears below.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&asn=12&include=peers,downstreams,upstreams,routes,whois_response'

Response

1
2{
3  "asn": {
4    "as_number": "AS12",
5    "organization": "New York University",
6    "country": "US",
7    ...
8    "peers": [
9      {
10        "as_number": "AS3269",
11        "description": "Telecom Italia S.p.A.",
12        "country": "IT"
13      },
14      {
15        "as_number": "AS8220",
16        "description": "COLT Technology Services Group Limited",
17        "country": "GB"
18      },
19      ...
20    ],
21    "downstreams": [
22      {
23        "as_number": "AS394666",
24        "description": "NYU Langone Health",
25        "country": "US"
26      },
27      {
28        "as_number": "AS54965",
29        "description": "Polytechnic Institute of NYU",
30        "country": "US"
31      }
32    ],
33    "upstreams": [
34      {
35        "as_number": "AS3269",
36        "description": "Telecom Italia S.p.A.",
37        "country": "IT"
38      },
39      {
40        "as_number": "AS8220",
41        "description": "COLT Technology Services Group Limited",
42        "country": "GB"
43      },
44      ...
45    ],
46    "whois_response": "\n\n\nASNumber:       12\nASName:         NYU-DOMAIN\nASHandle:       AS12\nRegDate:        1984-07-05\nUpdated:        2023-05-25 ..."
47    "routes": [
48      "192.76.177.0/24",
49      "216.165.96.0/20",
50      "216.165.89.0/24",
51      "216.165.0.0/18",
52      ...
53    ]
54  }
55}

B. Excluding Fields

You can exclude specific fields from the API response (except the ip field) by listing them in the excludes parameter as a comma-separated list. For example, you want to remove date_allocated and allocation_status from api response, you can put the keys in excludes parameter like this.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&asn=1&excludes=asn.date_allocated,asn.allocation_status'

Response

1{
2  "asn": {
3    "as_number": "AS1",
4    "organization": "Level 3 Parent, LLC",
5    "country": "US",
6    "asn_name": "LVLT-1",
7    "type": "BUSINESS",
8    "domain": "level3.com",
9    "num_of_ipv4_routes": "137",
10    "num_of_ipv6_routes": "0",
11    "rir": "ARIN"
12  }
13}

C. Get Specific fields

You can filter the API response to include only the fields you want by using the fields parameter. For example, to retrieve only the AS organization, its country, and downstreams in the API response, list these keys in the fields parameter as shown below. The API will combine these fields with the default ASN response. You can use the following URL.

Curl

Java

JQuery

Javascript

Node.js

PHP

Python

Swift

Ruby

curl -X GET 'https://api.ipgeolocation.io/v2/asn?apiKey=API_KEY&asn=25139&fields=asn.organization,asn.country,asn.downstreams

Response

1{
2  "asn": {
3    "organization": "Level 3 Parent, LLC",
4    "country": "US",
5    "downstreams": [
6      {
7        "as_number": "AS25139",
8        "description": "TVCABO - Comunicacoes Multimedia, Lda",
9        "country": "MZ"
10      }
11    ]
12  }
13}

Note: Parameters peers,downstreams,upstreams,whois_response can be used in both include , and fields . If both include and fields parameters are used simultaneously, only the fields parameter will be applied.

Reference to ASN API Response

Field	Type	Description	Can be empty?
ip	string	IP address for which asn data is required (appeared only when IP is queried).	Yes
asn.as_number	string	Complete Autonomous System Number that was looked up.	Yes
asn.organization	string	The name of the organization to which that ASN is assigned.	Yes
asn.country	string	The two‑letter country code where the organization is registered.	Yes
asn.asn_name	string	The official ASN handle.	Yes
asn.type	string	Type of the ASN (e.g. “isp”, “hosting”).	Yes
asn.domain	String	The domain associated with the ASN.	Yes
asn.date_allocated	string	The date the ASN was originally allocated.	Yes
asn.allocation_status	string	Current status of the ASN (“assigned”, “allocated”, etc.).	Yes
asn.num_of_ipv4_routes	string	Number of distinct IPv4 prefixes announced by this ASN.	Yes
asn.num_of_ipv6_routes	string	Number of distinct IPv6 prefixes announced by this ASN.	Yes
asn.peers	array	Directly connected ASes (asNumber, description, country).	Yes
asn.downstreams	array	Downstream (customer) ASNs with their details.	Yes
asn.upstreams	array	Upstream (provider) ASNs with their details.	Yes
asn.routes	array	IPv4 and IPv6 prefixes managed by provided ASN	Yes
asn.whois_response	string	Raw WHOIS record text returned for the ASN.	Yes

Error Codes

ASN API returns HTTP status code 200 for a successful API request along with the response.

While, in case of a bad or invalid request, ASN API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.

Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:

HTTP Status	Description
400 Bad Request	It is returned for one of the following reasons: If the provided IPv4, IPv6 address, or ASN is invalid. If special character(s) ( ) [ ] { } \| ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key.
401 Unauthorized	It is returned for one of the following reasons: If API key (as `apiKey` URL parameter) is missing from the request to IP ASN API. If an invalid (a random value) API key is provided. If the API request is made from an unverified ipgeolocation.io account. If your account has been disabled or locked to use by the admin due to abuse or illegal activity. When the request to IP ASN API is made using API key for a database subscription When the request to IP ASN API is made on the 'paused' subscription. If you’re making API requests after your subscription trial has been expired. If your active until date has passed and you need to upgrade your account. If IP-ASN lookup is called using free subsciption API key.
404 Not Found	It is returned for one of the following reasons: If the IPv4, IPv6, or ASN does not not exists in our database. If the IPv4, IPv6, or ASN is passed as a path variable, instead of url parameter as `ip=`, or `asn=`. If the wrong endpoint is called, that does not exists in our API.
405 Method Not Allowed	If wrong HTTP request method is used for calling the endpoints. Only GET method is allowed.
429 Too Many Requests	It is returned for one of the following reasons: If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'. If the surcharge API usage limit has reached against the subscribed plan.
499 Client Closed Request	If the client has set the very short request or connection timeout, leading to the server closing the request prematurely.
5XX Server Side Error	If a `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout), or `505` (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at support@ipgeolocation.io for further assistance.

API SDKs

To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

Our SDKs are also available on Github. Feel free to help us improve them. Following are the available SDKs:

ASN API FAQs

What is Autonomous System?

What is an ASN?

What is Border Gateway Protocol (BGP)?

What is routing policy?

What are upstreams and downstreams?

What are peers?

What data does IP to ASN API provide?

Are there free ASN lookup tools available?

How frequently is the ASN data updated?

How can I get ASN Database?

Can I perform lookups by IP address as well as ASN?

Can I have sample data of ASN db?

ASN Lookup API and Network Intelligence

ASN Lookup

Request

Response

Peer Relationships

Request

Response

Downstream ASNs

Request

Response

Upstream Providers

Request

Response

Routes

Request

Response

Whois Details

Request

Response

Response in Multiple Languages

Use Cases

Cybersecurity and Threat Detection

Network Performance and Routing Optimization

Business and Market Analysis

Fraud Detection and Prevention

Network Infrastructure Planning

Ready to get started?Get Started with ASN Lookup API Today

API Documents

Database Docs

ASN Lookup API Documentation

ASN Lookup API

Lookup By ASN

Response

Lookup By IP

Response

API Parameters

A. Including Data (include)

Response

- Include (Combine all objects with ASN details)

Response

B. Excluding Fields

Response

C. Get Specific fields

Response

Reference to ASN API Response

Error Codes

API SDKs

ASN API FAQs

Table of Contents