API Documentation

Programmatic access to BGPHorizon BGP data.

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header as a Bearer token.

Authorization: Bearer bgps_your_api_key_here

Base URL

https://bgphorizon.com/api/v1

Endpoints

POST /ip/lookup

Look up the origin ASN(s) for a list of IP addresses based on BGP routing data.

Request Body

{
  "ips": ["1.2.3.4", "8.8.8.8", "2001:4860:4860::8888"],
  "days_back": 7
}

ips

array of strings required

List of IPv4 or IPv6 addresses. Maximum 1000 per request.

days_back

integer optional, default: 7

Number of days to look back for BGP data. Valid range: 1-7.

Response

{
  "data": [
    {
      "requested_ip": "1.2.3.4",
      "asn": [1234]
    },
    {
      "requested_ip": "8.8.8.8",
      "asn": [15169]
    },
    {
      "requested_ip": "2001:4860:4860::8888",
      "asn": [15169]
    }
  ]
}

requested_ip

The IP address from your request.

asn

Array of ASN numbers that originated routes for this IP within the specified time period. Empty array if no routes found.

Example Request

curl -X POST https://bgphorizon.com/api/v1/ip/lookup \
  -H "Authorization: Bearer bgps_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"], "days_back": 7}'

Error Codes

400

Bad Request - Invalid request body, too many IPs, or invalid IP format.

401

Unauthorized - Missing or invalid API key.

500

Internal Server Error - Something went wrong on our end.

GET /events/export

Export BGP events (announcements and withdrawals) for a prefix or ASN as a streaming NDJSON download with gzip compression. Supports up to 2 million events per request.

Query Parameters

prefix

string required*

IP prefix in CIDR notation (e.g., 8.8.8.0/24) or a single IP address. Provide either prefix or asn, not both.

asn

string required*

Autonomous System Number (e.g., 15169 or AS15169). Provide either prefix or asn, not both.

start_date

string optional, default: 7 days ago

Start of date range in YYYY-MM-DD format.

end_date

string optional, default: today

End of date range in YYYY-MM-DD format.

event_type

string optional

Filter by event type: announcement or withdrawal.

limit

integer optional, default: 2000000

Maximum number of events to return. Valid range: 1 - 2,000,000.

Response Format

The response is a gzip-compressed stream of newline-delimited JSON (NDJSON). Each line is an independent JSON object representing one BGP event.

{"timestamp":"2026-07-01T12:00:00Z","event_type":"announcement","prefix":"8.8.8.0","prefix_len":24,"collector_id":"rrc00","peer_ip":"80.249.208.1","peer_asn":6777,"origin_as":15169,"as_path":[6777,15169],"communities":[],"next_hop":"80.249.208.1"}
{"timestamp":"2026-07-01T12:01:00Z","event_type":"withdrawal","prefix":"8.8.8.0","prefix_len":24, ...}

Response Headers

Content-Type

application/x-ndjson

Content-Encoding

gzip

X-Total-Count

Total number of matching events in the database (may exceed the limit).

X-Stream-Limit

Maximum number of events that will be returned in this response.

Event Fields

timestamp

ISO 8601 timestamp of the BGP event.

event_type

announcement or withdrawal.

prefix

The IP prefix (network address).

prefix_len

CIDR prefix length.

collector_id

Route collector that observed the event (e.g., rrc00).

peer_ip

IP address of the BGP peer.

peer_asn

ASN of the BGP peer.

origin_as

Origin ASN of the route.

as_path

Array of ASNs in the AS path.

communities

Array of BGP community strings.

next_hop

Next-hop IP address.

med

Multi-Exit Discriminator value (omitted if not set).

local_pref

Local preference value (omitted if not set).

Example Request

curl -o events.ndjson.gz \
  "https://bgphorizon.com/api/v1/events/export?prefix=8.8.8.0/24&start_date=2026-07-01&end_date=2026-07-07" \
  -H "Authorization: Bearer bgps_your_api_key_here"

Decompress and read with: zcat events.ndjson.gz | head -5

Python Example

import gzip, json, urllib.request

url = "https://bgphorizon.com/api/v1/events/export?asn=15169&limit=1000"
req = urllib.request.Request(url)
req.add_header("Authorization", "Bearer bgps_your_key")

with urllib.request.urlopen(req) as resp:
    data = gzip.decompress(resp.read())
    for line in data.decode().splitlines():
        event = json.loads(line)
        print(event["timestamp"], event["event_type"], event["prefix"])

Notes

The response is gzip-compressed. Most HTTP clients handle decompression automatically, but if saving to file use .ndjson.gz extension.
If X-Total-Count exceeds your limit, you can paginate by narrowing the date range across multiple requests.
BGP event data is retained for 95 days.

Error Codes

400

Bad Request - Invalid parameters (missing prefix/asn, bad date format, invalid limit).

401

Unauthorized - Missing or invalid API key.

502

Bad Gateway - Upstream BGP data service is unavailable.