ASN Lookup
Resolve an IP or ASN to Autonomous System metadata — owning organization, country, type (ISP, hosting, education, government), IP ranges, peers, and upstream/downstream relationships.
OpenAPI Specification
openapi: 3.0.7
info:
title: 'IPGeolocation.io: ASN Lookup API'
version: "3.0"
description: |
Retrieve Autonomous System Number (ASN) information associated with an
IPv4 address, IPv6 address, or a specific ASN.
The ASN Lookup API returns detailed information about an Autonomous System
including the ASN number, organization name, country of registration,
domain, ASN type, allocation date, and the Regional Internet Registry (RIR)
responsible for assigning the ASN.
Additional routing intelligence can also be retrieved including:
- Peering relationships
- Upstream and downstream connections
- IPv4 and IPv6 routing prefixes
- Raw WHOIS registry data
This information helps organizations analyze internet routing, identify
network operators, and understand how Autonomous Systems interconnect
across the internet.
One endpoint is available:
- **ASN lookup** (`GET /v3/asn`) returns ASN information for a single
IPv4 address, IPv6 address, or ASN number per request.
Use query parameters to control which fields are returned, include
routing relationships, or exclude fields to reduce response payload size.
## Authentication
Two authentication methods are supported:
### API Key
Pass your API key as the `apiKey` query parameter on every request. You can find your
key in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in
server-side environment variables. Avoid exposing it in client-side JavaScript.
### Request Origin (CORS)
Available on paid plans only. Whitelist your domain in the dashboard under the
"API Keys" section. Once configured, requests from that domain (and all its subdomains)
are accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),
not the full URL.
Each plan has a limit on the number of extra API keys and request origins:
| Plan | Extra API Keys + Request Origins |
|---|---|
| Starter (150K requests) | 1 |
| Core (250K requests) | 1 |
| Plus (500K requests) | 2 |
| Pro (1M requests) | 2 |
| Business (2M requests) | 3 |
| Premium (5M requests) | 3 |
Additional keys or origins can be added for $2.50 per month each.
## Response Formats
The API supports JSON (default) and XML output.
- Set the `output` query parameter to `json` or `xml`.
- Alternatively, set the `Accept` header to `application/json`, `application/xml`,
or `text/xml`.
If neither is specified, the response is returned as JSON. XML responses use a
`LinkedHashMap` root element.
## Credit Usage
Credits are charged only for successful **HTTP 200** responses. The exact number of
credits consumed by a request is returned in the `X-Credits-Charged` response header.
A **single ASN lookup** (`GET /v3/asn`) consumes **1 credit** per request.
## Field Filtering
Use `fields` to cherry-pick specific fields, or `excludes` to drop fields you do not
need. Both accept dot-notation for nested fields (e.g. `asn.as_number`,
`asn.organization`). The `ip` field is always present regardless of filters.
## Parameter Name Casing
Query parameter names are case-sensitive. Use exact names such as
`apiKey`, `ip`, `fields`, `include`, `excludes`, and `output`.
## Include Additional ASN Data
The `include` parameter can be used to retrieve additional routing
information related to the ASN.
Supported values include:
- `peers`
- `downstreams`
- `upstreams`
- `routes`
- `whois_response`
Multiple values must be comma-separated.
## Parameter Name Casing
Query parameter names are case-sensitive.
Use exact names such as `apiKey`, `ip`, `asn`, `include`,
`fields`, `excludes`, and `output`.
## ASN Data Availability
Basic ASN information is also included in the IP Geolocation API (`/v3/ipgeo`).
Field availability differs depending on the endpoint and subscription plan.
| Field | /v3/ipgeo (Free) | /v3/ipgeo (Paid) | /v3/asn |
|---|---|---|---|
| asn.as_number | ✓ | ✓ | ✓ |
| asn.organization | ✓ | ✓ | ✓ |
| asn.country | ✓ | ✓ | ✓ |
| asn.type | ✗ | ✓ | ✓ |
| asn.domain | ✗ | ✓ | ✓ |
| asn.date_allocated | ✗ | ✓ | ✓ |
| asn.rir | ✗ | ✓ | ✓ |
| asn.asn_name | ✗ | ✗ | ✓ |
| asn.allocation_status | ✗ | ✗ | ✓ |
| asn.num_of_ipv4_routes | ✗ | ✗ | ✓ |
| asn.num_of_ipv6_routes | ✗ | ✗ | ✓ |
| asn.peers | ✗ | ✗ | ✓ |
| asn.downstreams | ✗ | ✗ | ✓ |
| asn.upstreams | ✗ | ✗ | ✓ |
| asn.routes | ✗ | ✗ | ✓ |
| asn.whois_response | ✗ | ✗ | ✓ |
The `/v3/ipgeo` endpoint is recommended when you need IP geolocation data together
with basic ASN information.
The `/v3/asn` endpoint should be used when detailed ASN intelligence is required,
including routing relationships, routes, and WHOIS registry data.
## Usage Limits
Paid subscriptions do not enforce fixed daily or hourly rate limits.
If the monthly request quota is exceeded, requests continue and a surcharge
may be applied depending on the subscribed plan.
Requests made using invalid API keys or unsupported subscriptions
return **HTTP 401 Unauthorized**.
contact:
name: IPGeolocation Support
url: https://ipgeolocation.io/contact.html
email: [email protected]
termsOfService: https://ipgeolocation.io/tos.html
license:
name: Proprietary
url: https://ipgeolocation.io/tos.html
externalDocs:
description: IPGeolocation ASN Lookup API documentation
url: https://ipgeolocation.io/documentation/asn-api.html
servers:
- url: https://api.ipgeolocation.io
description: Production
security:
- ApiKeyAuth: []
paths:
/v3/asn:
get:
operationId: lookupASN
summary: IPGeolocation.io ASN Lookup
description: |
Returns ASN details for a single IPv4 address, IPv6 address,
or ASN number.
The response contains information about the Autonomous System
responsible for routing the queried IP address or ASN.
Basic ASN metadata is always returned, while additional routing
relationships such as peers, upstreams, downstreams, routes,
and WHOIS data can be retrieved using the `include` parameter.
When the lookup is performed using the `asn` parameter,
the `ip` field is not included in the response.
Each successful lookup consumes **1 credit**.
Use the `fields`, `excludes`, and `include` parameters
to customize the response.
tags:
- ASN Lookup
parameters:
- $ref: "#/components/parameters/Ip"
- $ref: "#/components/parameters/Asn"
- $ref: "#/components/parameters/Include"
- $ref: "#/components/parameters/Fields"
- $ref: "#/components/parameters/Excludes"
- $ref: "#/components/parameters/Output"
responses:
"200":
description: ASN information for the requested IP address.
headers:
X-Credits-Charged:
description: Number of API credits consumed by this request.
schema:
type: number
example: 1
content:
application/json:
schema:
$ref: "#/components/schemas/ASNLookupResponse"
example:
asn:
as_number: "AS24940"
organization: "Hetzner Online GmbH"
country: "DE"
type: "HOSTING"
domain: "hetzner.com"
date_allocated: "2002-06-03"
asn_name: "HETZNER-AS"
allocation_status: "ASSIGNED"
num_of_ipv4_routes: "84"
num_of_ipv6_routes: "6"
rir: "RIPE"
peers:
- as_number: "AS58057"
description: "Securebit A"
country: "CH"
- as_number: "AS28792"
description: "Public Internet Ltd"
country: "GB"
routes:
- "78.46.0.0/15"
- "138.199.128.0/17"
upstreams:
- as_number: "AS12552"
description: "GlobalConnect AB"
country: "SE"
- as_number: "AS58057"
description: "Securebit AG"
country: "CH"
downstreams:
- as_number: "AS209148"
description: "Securepoint GmbH"
country: "DE"
- as_number: "AS198167"
description: "Apptc.me s.r.o."
country: "CZ"
whois_response: |
#
# ARIN WHOIS data and services are subject to the Terms of Use
#
ASNumber: 24940
ASName: HETZNER-AS
OrgName: Hetzner Online GmbH
Country: DE
...
application/xml:
schema:
$ref: "#/components/schemas/ASNLookupResponse"
example: |
<LinkedHashMap>
<asn>
<as_number>AS24940</as_number>
<organization>Hetzner Online GmbH</organization>
<country>DE</country>
<type>HOSTING</type>
<domain>hetzner.com</domain>
<date_allocated>2002-06-03</date_allocated>
<asn_name>HETZNER-AS</asn_name>
<allocation_status>ASSIGNED</allocation_status>
<num_of_ipv4_routes>84</num_of_ipv4_routes>
<num_of_ipv6_routes>6</num_of_ipv6_routes>
<rir>RIPE</rir>
<peers>
<as_number>AS58057</as_number>
<description>Securebit AG</description>
<country>CH</country>
</peers>
<peers>
<as_number>AS28792</as_number>
<description>Public Internet Ltd</description>
<country>GB</country>
</peers>
<routes>78.46.0.0/15</routes>
<routes>138.199.128.0/17</routes>
<upstreams>
<as_number>AS12552</as_number>
<description>GlobalConnect AB</description>
<country>SE</country>
</upstreams>
<upstreams>
<as_number>AS58057</as_number>
<description>Securebit AG</description>
<country>CH</country>
</upstreams>
<downstreams>
<as_number>AS209148</as_number>
<description>Securepoint GmbH</description>
<country>DE</country>
</downstreams>
<downstreams>
<as_number>AS198167</as_number>
<description>Apptc.me s.r.o.</description>
<country>CZ</country>
</downstreams>
<whois_response>
ASNumber: 24940
OrgName: Hetzner Online GmbH
Country: DE
...
</whois_response>
</asn>
</LinkedHashMap>
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"405":
$ref: "#/components/responses/MethodNotAllowed"
"423":
$ref: "#/components/responses/Locked"
"429":
$ref: "#/components/responses/TooManyRequests"
"499":
$ref: "#/components/responses/ClientClosedRequest"
"500":
$ref: "#/components/responses/InternalServerError"
"502":
$ref: "#/components/responses/BadGateway"
"503":
$ref: "#/components/responses/ServiceUnavailable"
"504":
$ref: "#/components/responses/GatewayTimeout"
"505":
$ref: "#/components/responses/HttpVersionNotSupported"
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
Ip:
name: ip
in: query
required: false
description: |
An IPv4 address or IPv6 address to look up. When omitted, the API
resolves the public IP of the requesting client.
If the `asn` parameter is provided, the `ip` parameter must not be used,
because the lookup will be performed directly using the specified ASN.
Empty or whitespace-only values are treated the same as omission and resolve
the caller IP.
Pass `ip` only once. If multiple `ip` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
examples:
none:
summary: No IP address provided
value: ""
ipv4:
summary: IPv4 address
value: "91.128.103.196"
ipv6:
summary: IPv6 address
value: "2607:fb91:16c6:8860:e531:2d1d:4944:6c7c"
Asn:
name: asn
in: query
required: false
description: |
An Autonomous System Number (ASN) to look up.
When provided, the lookup is performed directly using the specified ASN,
and the `ip` parameter must not be included in the request.
The API returns detailed information about the ASN including the
organization name, country of registration, ASN type, routing statistics,
and other related network metadata.
Pass `asn` only once. If multiple `asn` query parameters are sent,
values may be merged and treated as invalid input (HTTP 400).
schema:
type: string
examples:
none:
summary: No ASN provided
value: ""
numeric:
summary: ASN number
value: "24940"
prefixed:
summary: ASN with prefix
value: "AS24940"
Include:
name: include
in: query
required: false
description: |
Comma-separated list of optional data modules to add to the response. These are
not returned by default.
Supported ASN modules include:
- `peers`
- `downstreams`
- `upstreams`
- `routes`
- `whois_response`
If multiple values are provided, they must be comma-separated.
For additional query parameters (`include`, `fields`, `excludes`, `output`),
unknown values are ignored. The API still returns HTTP 200 and applies only
recognized values.
schema:
type: string
examples:
none:
summary: Do not include any optional modules
value: ""
peers:
summary: Include ASN peer relationships
value: "peers"
multiple:
summary: Include peers and downstream connections
value: "peers,downstreams"
routingData:
summary: Include routing relationships and routes
value: "peers,downstreams,upstreams,routes"
all:
summary: Include all ASN modules
value: "peers,downstreams,upstreams,routes,whois_response"
Fields:
name: fields
in: query
required: false
description: |
Comma-separated list of fields or objects to return. Everything else is omitted.
The `ip` field is always returned when the lookup is performed using an IP address.
Supports dot-notation for nested fields: `asn.organization`, `asn.domain`.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
If you list both an object key and one of its nested fields separated by comma
(e.g. `asn,asn.organization`), the full object is returned.
Unknown field paths are ignored. The API still returns HTTP 200.
Available on all plans including Free.
schema:
type: string
examples:
none:
summary: Return the full response (no field filtering)
value: ""
countryOnly:
summary: Return only the ASN country field
value: "asn.country"
moreThanOneFields:
summary: Return specific ASN fields
value: "asn.organization,asn.country"
Excludes:
name: excludes
in: query
required: false
description: |
Comma-separated list of fields or objects to remove from the response.
The `ip` field cannot be excluded.
Supports dot-notation for nested fields: `asn.domain`.
If the same field or object is specified in both `fields` and `excludes`, the
object is still returned, but it will be empty.
Unknown fields or object keys in `excludes` are ignored. The API still returns
HTTP 200.
Available on all plans including Free.
schema:
type: string
examples:
none:
summary: Do not exclude any fields
value: ""
excludeObjects:
summary: Exclude ASN allocation metadata
value: "asn.date_allocated,asn.allocation_status"
Output:
name: output
in: query
required: false
description: |
Desired response format. Defaults to `json` if not specified. You can also
control the format using the `Accept` header (`application/json`,
`application/xml`, or `text/xml`). If both are provided, the `output` parameter
takes precedence.
If `output` is unknown or unsupported, it is ignored and the response defaults
to JSON (`application/json`) with HTTP 200.
schema:
type: string
enum: [json, xml]
default: json
responses:
BadRequest:
description: |
Bad request. Returned for one of the following reasons:
- The provided IPv4 address or IPv6 address is invalid.
- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,
either in a parameter name or its value (especially in the API key).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
invalidIp:
summary: Invalid IPv4/IPv6 input
value:
message: "Provided name, service or IP address '999.999.999.999' is not valid."
specialCharacters:
summary: Special characters in API URL or key
value:
message: "Invalid character found in the request target."
Unauthorized:
description: |
Unauthorized. Returned for one of the following reasons:
- The `apiKey` URL parameter is missing.
- An invalid (random or incorrect) API key is provided.
- The account has been disabled or locked due to abuse or illegal activity.
- The API request is made using an API key for a database subscription.
- The API request is made using a free subscription API key.
- The subscription is in a 'paused' state.
- The subscription trial has expired.
- The account’s active-until date has passed and renewal or upgrade is required.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
missingApiKey:
summary: Missing API key
value:
message: "Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login"
invalidApiKey:
summary: Invalid API key
value:
message: "Provided API key is not valid. Contact technical support for assistance at [email protected]"
lockedAccount:
summary: Account locked or disabled
value:
message: "Your account has been locked to use IPGeolocation API. Contact technical support for assistance at [email protected]"
databaseSubscriptionKey:
summary: Database subscription API key used for REST API
value:
message: "You cannot query IPGeolocation API on a database plan subscription. "
freePlanAccess:
summary: Free subscription used for ASN lookup API
value:
message: "ASN Lookup is not supported on your current subscription. This feature is available to Paid subscriptions only."
pausedSubscription:
summary: Subscription is paused
value:
message: "Your subscription has been paused. Please resume your subscription to use IPGeolocation API."
expiredSubscription:
summary: Subscription expired or trial ended
value:
message: "Your subscription has expired at DATE. Please subscribe to a paid plan to continue using IPGeolocation API without interruption or contact technical support for assistance at [email protected]"
NotFound:
description: |
Not found. Returned for one of the following reasons:
- A syntactically valid IPv4, IPv6, or ASN does not exist in the IPGeolocation database.
- An IPv4, IPv6, or ASN is passed as a path variable
instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`
instead of `/v3/ipgeo?ip=8.8.8.8`).
- A non-existent or incorrect API endpoint is called.
Invalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
ipNotInDatabase:
summary: IPv4/IPv6/ASN not found in database
value:
message: "Provided ASN or IP Address does not exist in our database."
ipAsPathVariable:
summary: IP passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/ipgeo/8.8.8.8."
asnAsPathVariable:
summary: ASN passed as path variable instead of query parameter
value:
message: "No endpoint GET /v3/ipgeo/24940."
wrongEndpoint:
summary: Incorrect or non-existent endpoint
value:
message: "No endpoint GET /v3/asn-invalid."
MethodNotAllowed:
description: |
Method Not Allowed. Returned when an unsupported HTTP method is used
to call an endpoint.
Only the **GET** method is supported for the ASN lookup API endpoint.
Any other HTTP method results in HTTP 405.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
postNotAllowed:
summary: POST method used
value:
message: "Request method 'POST' is not supported"
unsupportedMethod:
summary: Unsupported HTTP method
value:
message: "Request method is not supported"
Locked:
description: |
Locked. The provided IP address belongs to a bogon IP range or a private
network and cannot be looked up.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "'10.0.0.1' is a bogon IP address."
TooManyRequests:
description: |
Too Many Requests. Returned for one of the following reasons:
- The API usage limit has been reached for a Paid subscription with
status 'past due', 'deleted', or 'trial expired'.
- The surcharge API usage limit has been reached for the subscribed plan.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
examples:
usageLimitReached:
summary: API usage limit reached
value:
message: "You have exceeded the limit of PLAN_USAGE_LIMIT requests per PLAN_INERVAL for your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation
API without interruption."
surchargeLimitReached:
summary: Surcharge usage limit reached
value:
message: "You have reached the surcharge amount limit of PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue
using IPGeolocation API without interruption."
ClientClosedRequest:
description: |
The client closed the connection before the server finished processing the
request. This usually happens when the client sets a very short request or
connection timeout. Increase the timeout on the client side.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Client closed the request before the server could respond."
InternalServerError:
description: |
Internal Server Error. The server encountered an unexpected condition
that prevented it from fulfilling the request. If the issue persists,
contact [email protected].
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Something went wrong on the server side."
BadGateway:
description: |
Bad Gateway. The API server received an invalid response from an upstream
server while processing the request. This is usually temporary.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Upstream service error. Please try again later."
ServiceUnavailable:
description: |
Service Unavailable. The API is temporarily unavailable due to maintenance
or overload. Please try again later.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "Service temporarily unavailable. Please try again later."
GatewayTimeout:
description: |
Gateway Timeout. The API server did not receive a timely response from
an upstream server.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "The server timed out while processing the request."
HttpVersionNotSupported:
description: |
HTTP Version Not Supported. The server does not support the HTTP protocol
version used in the request.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: "HTTP version not supported."
schemas:
ErrorResponse:
type: object
description: |
Returned for any non-200 response. Contains only a human-readable `message`.
Message text can vary by status and condition; examples in this spec are
representative, not exhaustive, and should not be treated as stable machine
codes.
required:
- message
properties:
message:
type: string
description: Human-readable explanation of what went wrong. Use HTTP status for control flow.
example: "Provided name, service or IP address '999.999.999.999' is not valid."
ASNLookupResponse:
type: object
xml:
name: LinkedHashMap
description: |
Response returned by the ASN Lookup API.
Contains the queried IP address (when an IP lookup is performed) and
the ASN information associated with the network responsible for routing
that IP address.
When the lookup is performed using the `asn` parameter, the `ip` field
is not included in the response.
properties:
ip:
type: string
description: |
The IP address for which ASN details are returned. This field appears
only when the lookup is performed using an IP address.
example: "49.12.0.0"
asn:
$ref: "#/components/schemas/ASN"
ASN:
type: object
description: |
ASN information describing the Autonomous System responsible for routing
the queried IP address or the specified ASN. Costs 1 credit.
properties:
as_number:
type: string
description: Complete Autonomous System Number that was looked up.
example: "AS24940"
organization:
type: string
description: Name of the organization to which the ASN is assigned.
example: "Hetzner Online GmbH"
country:
type: string
description: ISO 3166-1 alpha-2 country code where the ASN is registered.
example: "DE"
asn_name:
type: string
description: Official ASN handle.
example: "HETZNER-AS"
type:
type: string
description: |
ASN category. Possible values include `ISP`, `HOSTING`, `BUSINESS`,
`EDUCATION`, or `GOVERNMENT` when available.
example: "HOSTING"
domain:
type: string
description: Domain associated with the ASN.
example: "hetzner.com"
date_allocated:
type: string
description: Date when the ASN was originally allocated.
example: "2002-06-03"
rir:
type: string
description: |
Regional Internet Registry that allocated the ASN.
Examples include `RIPE`, `ARIN`, `APNIC`, `LACNIC`, `AFRINIC`, etc.
example: "RIPE"
allocation_status:
type: string
description: Current allocation status of the ASN.
example: "ASSIGNED"
num_of_ipv4_routes:
type: string
description: Number of IPv4 prefixes announced by this ASN.
example: "84"
num_of_ipv6_routes:
type: string
description: Number of IPv6 prefixes announced by this ASN.
example: "6"
peers:
type: array
description: Directly connected peer ASNs.
items:
$ref: "#/components/schemas/ASNConnection"
downstreams:
type: array
description: Downstream (customer) ASNs connected to this ASN.
items:
$ref: "#/components/schemas/ASNConnection"
upstreams:
type: array
description: Upstream provider ASNs used for internet connectivity.
items:
$ref: "#/components/schemas/ASNConnection"
routes:
type: array
description: IPv4 and IPv6 prefixes announced by this ASN.
items:
type: string
examples:
- "192.76.177.0/24"
- "2607:f600::/32"
whois_response:
type: string
description: Raw WHOIS registry record text returned for the ASN.
example: "ASNumber: 24940\nOrgName: Hetzner Online GmbH\nCountry: DE"
ASNConnection:
type: object
description: |
Represents a connected Autonomous System such as a peer,
upstream provider, or downstream customer.
properties:
as_number:
type: string
description: Autonomous System Number of the connected network.
example: "AS3356"
description:
type: string
description: Name or description of the connected network
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ipgeolocation/refs/heads/main/openapi/ipgeolocation-asn-openapi.yml