API Documentation

The BGPScout API allows you to query network data, retrieve ASN details, and submit traceroute results. All responses are JSON unless otherwise noted.

Base URL:https://bgpscout.io/api

Trace Processing Pipeline

Every traceroute submitted to BGPScout goes through a multi-stage enrichment pipeline before being included in any analysis or public results:

1. Submission — Raw MTR/traceroute data is received via the API or RIPE Atlas.
2. Enrichment — Each hop IP is resolved to an ASN (via BGP prefix tables), geolocated (via geofeed, IPinfo, MaxMind), and classified (anycast, IXP, cloud, etc.).
3. Quality Scoring — A 0-10 data quality score is computed based on: PTR record coverage, geo coverage, hop completion ratio, and path coherence.
4. Display Gating — Traces with quality score ≤ 2 are auto-rejected. Scores 3-5 go to pending review. Scores 6+ are auto-approved. Only approved traces appear in search results and analysis.

Boomerang Detection

A "boomerang route" is detected when a traceroute from country A to a destination also in country A transits through a different country. This indicates suboptimal routing where domestic traffic unnecessarily crosses international borders.

Data Sources

• Traceroutes — User-submitted MTR tests, RIPE Atlas measurements, automated probes in 30+ countries
• ASN Data — ARIN, RIPE NCC, APNIC, LACNIC, AFRINIC registry data
• PeeringDB — Facility presence, IXP memberships, port speeds
• GeoIP — Geofeed (RFC 8805), IPinfo, MaxMind, PTR hostname analysis
• Domain Intelligence — Certificate Transparency, DNS enumeration, WHOIS

Some endpoints require an API key passed via the X-API-Key HTTP header. Public endpoints do not require authentication.

To obtain an API key, log in and visit your Account Settings page.

curl -H "X-API-Key: your_api_key_here" \
     https://bgpscout.io/api/traceroutes/submit

All endpoints are rate-limited to 100 requests per hour per API key (or per IP for unauthenticated requests). Exceeding this limit returns a 429 response.

Returns aggregate statistics about all collected traceroutes.

Example Request

curl https://bgpscout.io/api/traceroutes/stats

Example Response

{
  "success": true,
  "stats": {
    "total_traces": 14523,
    "source_countries": 12,
    "unique_destinations": 987,
    "unique_source_asns": 45,
    "boomerang_count": 312,
    "leaves_country_count": 1804,
    "earliest_trace": "2025-01-15T00:00:00.000Z",
    "latest_trace": "2026-04-02T18:30:00.000Z"
  },
  "top_source_countries": [
    { "source_country": "CA", "trace_count": 9821 },
    { "source_country": "US", "trace_count": 3104 }
  ]
}

Submit one or more traceroute results for storage and analysis.

Headers

Request Body

{
  "traces": [
    {
      "host": "example.com",
      "dest_ip": "93.184.216.34",
      "source_ip": "192.168.1.1",
      "source_country": "CA",
      "platform": "linux",
      "tool": "mtr",
      "completed": true,
      "hops": [
        {
          "hop_number": 1,
          "ip": "192.168.1.1",
          "hostname": "gateway.local",
          "rtt_avg": 1.2,
          "rtt_min": 0.8,
          "rtt_max": 2.1,
          "loss_pct": 0
        },
        {
          "hop_number": 2,
          "ip": "10.0.0.1",
          "rtt_avg": 5.4
        }
      ]
    }
  ]
}

Hop Fields

Example Response

{
  "success": true,
  "trace_ids": [1042, 1043],
  "count": 2
}

Error Response

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "trace_index": 0, "errors": ["Invalid dest_ip format"] }
  ]
}

Returns detailed information about an ASN including peering quality and route scoring.

Parameters

Example Request

curl https://bgpscout.io/api/asn/577

Example Response

{
  "asn": 577,
  "name": "BACOM",
  "country": "CA",
  "rir": "arin",
  "traffic_level": "Medium",
  "network_type": "NSP",
  "on_ix": true,
  "peering_quality": {
    "crossing_rate": 0.12,
    "quality_tag": "Good"
  },
  "route_score": {
    "quality": 78.5,
    "route": 82.1,
    "overall": 80.3
  },
  "url": "https://bgpscout.io/asns/577"
}

Returns a self-contained HTML card for an ASN that can be embedded via an iframe.

Usage

<iframe src="https://bgpscout.io/api/embed/asn/577"
        width="320" height="200"
        frameborder="0"></iframe>

Preview

The widget displays the ASN name, country, peering quality badge, route score, and a link back to BGPScout.