IP to ASN Web Service - Container Images¶

Debian-based container images for the IP to ASN Web Service. Two variants are published to one registry.

Variants & Tags¶

Why a fork variant? The fork-maintained by @rda0-is a drop-in compatible superset of the original. It adds bulk IP lookups, direct ASN queries, listings of all ASNs, and subnet enumeration for a given ASN. Use Original for a minimal surface; choose Fork when you need richer discovery workflows or automation against AS/ASN data.

Original variant - API Usage¶

Routes¶

• /v1/as/ip/<ip address> Lookup provided IP address.

• /v1/as/ip Lookup requester's IP address, prioritized as X-Real-IP → X-Forwarded-For → request IP.

JSON Response¶

curl -H 'Accept: application/json' http://localhost:53661/v1/as/ip/8.8.8.8

Fork variant - API Usage¶

Routes¶

• GET /v1/as/ip/<ip address> Lookup provided IP address.

• GET /v1/as/ip Lookup requester's IP address, prioritized as X-Real-IP → X-Forwarded-For → request IP.

• PUT /v1/as/ips Bulk lookup provided list of IP addresses.

• GET /v1/as/n/<as number> Lookup provided AS number.

• GET /v1/as/ns Returns all known AS numbers.

• GET /v1/as/n/<as number>/subnets Returns all known subnets of a given AS number.

JSON Response¶

curl -H 'Accept: application/json' http://localhost:53661/v1/as/ip/8.8.8.8

Returns JSON:

{
  "announced": true,
  "as_country_code": "US",
  "as_description": "GOOGLE - Google LLC",
  "as_number": 15169,
  "first_ip": "8.8.8.0",
  "ip": "8.8.8.8",
  "last_ip": "8.8.8.255"
}

HTML Response¶

curl http://localhost:53661/v1/as/ip/8.8.8.8

Returns a formatted HTML page with the IP information.

Plain Response¶

curl -H 'Accept: text/plain' http://localhost:53661/v1/as/ip/8.8.8.8

Returns plaintext:

15169 | 8.8.8.0-8.8.8.255 | US | GOOGLE

Bulk IP - JSON¶

echo '["8.8.8.8","8.8.4.4"]' \
  | curl -H "Accept: application/json" -X PUT --json @- http://localhost:53661/v1/as/ips

Returns JSON:

[
  {
    "ip": "8.8.8.8",
    "announced": true,
    "first_ip": "8.8.8.0",
    "last_ip": "8.8.8.255",
    "as_number": 15169,
    "as_country_code": "US",
    "as_description": "GOOGLE"
  },
  {
    "ip": "8.8.4.4",
    "announced": true,
    "first_ip": "8.8.4.0",
    "last_ip": "8.8.4.255",
    "as_number": 15169,
    "as_country_code": "US",
    "as_description": "GOOGLE"
  }
]

Bulk IP - Plain¶

echo -e '8.8.8.8\n8.8.4.4' \
  | curl -H "Accept: text/plain" -X PUT --data-binary @- http://localhost:53661/v1/as/ips

Or with explicit begin/end markers:

echo -e 'begin\n8.8.8.8\n8.8.4.4\nend' \
  | curl -H "Accept: text/plain" -X PUT --data-binary @- http://localhost:53661/v1/as/ips

Returns plaintext:

15169    | 8.8.8.8              | GOOGLE, US
15169    | 8.8.4.4              | GOOGLE, US

Unannounced IPs¶

For IP addresses not found in BGP announcements:

{
  "announced": false,
  "ip": "127.0.0.1"
}

AS Number Lookup¶

ASNs can be provided as 15169 or AS15169.

curl -H 'Accept: application/json' http://localhost:53661/v1/as/n/15169

Plaintext:

curl -H 'Accept: text/plain' http://localhost:53661/v1/as/n/15169

Response format:

15169 | US | GOOGLE

AS Numbers Listing¶

Returns all known AS numbers:

curl -sH 'Accept: text/plain' http://localhost:53661/v1/as/ns | rg -S google

Example output:

15169 | US | GOOGLE
16550 | US | GOOGLE-PRIVATE-CLOUD
16591 | US | GOOGLE-FIBER
19527 | US | GOOGLE-2
...

AS Subnets Lookup¶

Returns all IP subnets of a given AS in CIDR format.

curl -H 'Accept: application/json' http://localhost:53661/v1/as/n/15169/subnets

Example JSON:

{
  "as_number": 15169,
  "subnets": [
    "8.8.4.0/24",
    "8.8.8.0/24",
    "..."
  ]
}

Plaintext:

curl -H 'Accept: text/plain' http://localhost:53661/v1/as/n/15169/subnets

8.8.4.0/24
8.8.8.0/24
...

Note: These subnets are not necessarily identical to the currently announced BGP prefixes; multiple announced prefixes may be represented by a single subnet here. To query announced prefixes, see RIPE’s “announced-prefixes” API.

The in BGP announced prefixes can be queried from the ripe database: https://stat.ripe.net/docs/data-api/api-endpoints/announced-prefixes

Attribution¶

Parts of the Fork variant documentation are adapted from @rda0’s project: https://github.com/rda0/iptoasn-webservice