📡 bgproutes.io API Documentation

Welcome to the bgproutes.io API — your streamlined gateway to fast and easy access to our BGP data. The API is served over HTTPS at api.bgproutes.io on port 443, and offers endpoints to query:

• Vantage point list and metadata
• BGP update entries
• Routing Information Base (RIB) snapshots
• AS-level topologies

With this API, you can retrieve data in near real time, with updates and RIB being available within 1 to 2 minutes of collection. The data is retained for up to 7 days using a sliding window mechanism, giving you full visibility into both current and past BGP activity. The vantage_points page indicates the earliest date from which data is available in our database.

💡 In most cases, we recommend using our Python client.
It provides a more convenient and scriptable way to access the data.

We are actively working on scaling our infrastructure. Our goal is to extend data retention to several months in the near future.

---

🔐 Authentication

All endpoints require an API key for authentication. To get started, generate your key from the API Key page. Be sure to copy and store it securely — it will only be shown once. Once you have your key, include it in the x-api-key header of your requests, like so if you use curl:

-H "x-api-key: YOUR_API_KEY"

Example

Here is a curl command that queries the update endpoint of our API, with the API KEY rtgi34-eo453igjeoi.

curl -X GET "https://api.bgproutes.io/updates?vp_ip=2.2.2.2&start_date=2025-09-01T00:00:00&end_date=2025-09-01T23:59:59" -H "accept: application/json" -H "x-api-key: rtgi34-eo453igjeoi"

---

🚦 Rate Limiting

Each API key is subject to usage limits to ensure fair access for all users:

• Maximum requests per hour: 1000
• Maximum total server execution time per hour: 5 minute
• Maximum data volume downloaded per hour: 100MB
• Maximum number of concurrent query: 1 (only one request can be processed at a time per API key)

Requests exceeding these limits will be rejected with status code 429 Too Many Requests.

To help you manage your usage, every successful response includes the server execution time and downloaded bytes for that request. You can use this information to monitor your usage and optimize your queries accordingly to stay within your limits.

Are the rate limits too restrictive? Just email us at contact@bgproutes.io. We’ll do our best to adjust them for you.

---

🧠 Filtering Logic

Each endpoint supports a variety of filtering options to help you retrieve only the data that matters — reducing unnecessary downloads and saving server resources. We strongly encourage using these filters wherever possible to get more value from your queries while minimizing load.

Unless specified otherwise, filters operate under the following logic:

• AND logic across filters: Multiple filters must all be satisfied for a result to be included (e.g., both prefix_exact_match and aspath_regexp must match).
• OR logic within filters: If a filter accepts multiple values, any of them may match (e.g., multiple entries in prefix_exact_match or prefix_filter).

Example

If you set prefix_exact_match=1.0.0.0/24,2.0.0.0/24, results will include data for either of these prefixes. If you also set aspath_regexp=' 2914 ', the returned data must match both:

• The prefix is 1.0.0.0/24 or 2.0.0.0/24, and
• The AS path includes AS2914.

---

📘 Endpoints

⚠️ Note: All date parameters must be provided in UTC and in the iso format, for instance: 2025-05-10T12:10:05.

/vantage_points

Get BGP vantage points with optional filters.

Query Parameters:

• vp_ips (optional): Comma-separated list of VP IP addresses. Only VPs matching these IPs will be returned.
• vp_asns (optional): Comma-separated list of ASNs. Returns only VPs that belong to these ASes.
• ip_protocol (optional): Filter in the IP protocol (4 or 6).
• source (optional): Comma-separated list of data sources. Sources refer to the platforms operating the VPs and may include: ris, routeviews, pch, bgproutes.io, or cgtf.
• country (optional): Comma-separated list of ISO country codes (e.g., FR,US). Returns only VPs located in these countries.
• rib_size_v4 (optional): Filter on IPv4 RIB size. Use format OPERATOR,VALUE (e.g., >,100000). Only VPs whose IPv4 RIB size satisfies the condition will be returned.
• rib_size_v6 (optional): Filter on IPv6 RIB size. Use format OPERATOR,VALUE (e.g., >=,10000). Only VPs whose IPv6 RIB size satisfies the condition will be returned.
• return_uptime_intervals (optional): Set to True to include uptime intervals for each VP in the response.

Output

The endpoint returns a list of vantage points. Each vantage point has the following attributes:

• ip: The IP address of the vantage point.
• asn: The Autonomous System Number to which the vantage point belongs.
• source: The platform that operates this vantage point (e.g., bgproutes.io, ris, routeviews, pch).
• is_active: A boolean indicating whether the vantage point is currently active.
• rib_size_v4: The number of IPv4 prefixes visible in the RIB of the vantage point.
• rib_size_v6: The number of IPv6 prefixes visible in the RIB of the vantage point.
• org_name: The name of the organization that owns or operates the vantage point.
• org_country: The ISO country code (e.g., US, FR) of the organization.
• date_insert: The date when the vantage point was added to the system (format: YYYY-MM-DD).
• uptime_intervals: If requested, a list of tuples representing the UNIX timestamps during which the vantage point was considered up.

Examples 1:

Retrieve all vantage points located in France or the United States that are operated by either bgproutes.io or PCH.

curl -X GET "https://api.bgproutes.io/vantage_points?country=FR,US&source=bgproutes.io,pch" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
    "seconds":0.0070421695709228516,
    "bytes":68484,
    "data":[
        {"ip":"1.1.1.1", "asn":10, "source":"bgproutes.io","is_active":true,"rib_size_v4":900000,"rib_size_v6":0,"org_name":"Test Org","org_country":"FR","date_insert":"2025-04-23 19:38:39.975891+02","uptime_intervals":null},
        {"ip":"2.2.2.2","asn":2,"source":"pch","is_active":true,"rib_size_v4":0,"rib_size_v6":124212,"org_name":"MyOrgv6","org_country":"US","date_insert":"2025-02-23 19:38:39.984006+02","uptime_intervals":null},
        ...
        ]
}

Examples 2:

Retrieve all vantage points whose IPv4 RIB size exceeds 800,000, and include their uptime intervals in the response.

curl -X GET "https://api.bgproutes.io/vantage_points?rib_size_v4=>,800000&return_uptime_intervals=True" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
    "seconds":0.0070421695709228516,
    "bytes":68484,
    "data":[
        {"ip":"1.1.1.1", "asn":10, "source":"bgproutes.io","is_active":true,"rib_size_v4":900000,"rib_size_v6":0,"org_name":"Test Org","org_country":"FR","date_insert":"2024-04-23 19:38:39.975891+02","uptime_intervals":[(1713897649,1724438449),(1737657649,1740336049),(1745433649,1748025649)]},
        {"ip":"1.1.1.2", "asn":2431, "source":"routeviews","is_active":false,"rib_size_v4":930000,"rib_size_v6":0,"org_name":"ISP Test","org_country":"GE","date_insert":"2025-01-23 19:38:39.975891+02","uptime_intervals":[(1737657649,1740335049)]},
        ...
        ]
}

---

/updates

Get BGP updates from a vantage point during a time window.

Query Parameters:

• vp_ip (required): IP address of the vantage point.
• start_date (required): Start of the time window. ISO Format: YYYY-MM-DDTHH:MM:SS.
• end_date (required): End of the time window. ISO Format: YYYY-MM-DDTHH:MM:SS.
• return_count (optional): If set to True, returns only the count of matching entries (e.g., number of withdrawals), avoiding full data download.
• chronological_order (optional): Whether to return updates in chronological order. Default is True.
• max_updates_to_return (optional): Limits the number of updates returned. By default, all matching updates are returned.
• with_as_set (optional): Determines whether AS paths including an AS set should be returned.
  • True (default): AS paths with AS sets are returned; they are represented as strings (e.g., 1234 4534 {13,124} 34).
  • False: AS paths with AS sets are not returned; the returned AS paths (all other AS paths) are a list of integers.
• type_filter (optional): Filter on update type. Use 'A' for Announcements only, 'W' for withdrawals only. Default is None, meaning both types.
• prefix_filter (optional): Comma-separated list of prefix conditions in the form OPERATOR:CIDR.
  Operators follow PostgreSQL CIDR semantics, such as:
  • <<:1.0.0.0/8 (prefix contained in)
  • =:2.2.2.2/24 (exact match)
• prefix_exact_match (optional): Comma-separated list of prefixes for exact matching.
  💡 Use this over prefix_filter for better performance when exact matching is sufficient.
• return_aspath (optional): Include AS path in the result. Default is True.
  Set to False to reduce response size and execution time when AS path data is not needed.
• aspath_exact_match (optional): Comma-separated list of AS paths for exact matching. 💡 Use this over aspath_regexp for better performance when exact matching is sufficient.
• aspath_regexp (optional): Regex filter on AS path. Internally uses PostgreSQL pattern matching. The expression must not exceed 100 characters for security reasons. Example: ^2914|2914$ matches paths that start or end with 2914.
• return_community (optional): Include BGP communities in the response. Default is True.
  Set to False to reduce response size and improve execution time if community data is not required.
• community_regexp (optional): Regex on BGP community values, using PostgreSQL regex syntax. The expression must not exceed 100 characters for security reasons. Example: 100:10 100:20|100:30 matches entries with communities 100:10 100:20 or 100:30.

Examples 1:

Retrieve all updates (excluding community values) observed by vantage point 1.1.1.1 between July 31, 2025 at 20:19:19 and July 31, 2025 at 22:23:24, where:

• the AS path contains AS3333, excluding occurrences at the beginning or end,
• and the prefix is contained within 8.0.0.0/8.

curl -X GET "https:/api.bgproutes.io/updates?vp_ip=1.1.1.1&start_date=2025-07-31T20:19:19&end_date=2025-07-31T22:23:24&return_community=False&aspath_regexp='%203333%20'&prefix_filter=<<:8.0.0.0/8" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
  "seconds": 0.0037958621978759766,
  "bytes": 24355,
  "data": [[1744287050.0, "A", "8.0.10.0/16", "131477 3333 140096 3491 4637 1221"], [1744287450.0, "A", "8.0.0.0/24", "131477 65511 140096 140096 9318"], [1744288050.0, "A", "8.0.0.0/24", "131477 65511 140096 3333 9680 3462"]]
}

⚠️ Be aware of URL encoding! When writing your curl commands, make sure to properly encode special characters. For example, to match AS3333 appearing in the middle of the AS path, you should encode the space characters around 3333 — turning 3333 into %203333%20.

Examples 2:

Retrieve the number of withdrawals for prefixes 45.0.0.0/24 and 54.0.0.0/16 (combined) observed by vantage point 2.2.2.2 between July 31, 2025 at 20:19:19 and July 31, 2025 at 22:23:24.

curl -X GET "https://api.bgproutes.io/updates?vp_ip=2.2.2.2&start_date=2025-07-31T20:19:19&end_date=2025-07-31T22:23:24&type_filter='W',prefix_exact_match=45.0.0.0/24,54.0.0.0/16&return_count=True" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
  "seconds": 0.0045679,
  "bytes": 14355,
  "data": 10
}

Examples 3:

Retrieve the last withdrawals for prefixes 221.0.0.0/24 observed by vantage point 3.3.3.3 within the interval July 31, 2025 at 20:19:19 and July 31, 2025 at 22:23:24.

curl -X GET "https://api.bgproutes.io/updates?vp_ip=3.3.3.3&start_date=2025-07-31T20:19:19&end_date=2025-07-31T22:23:24&type_filter='W',prefix_exact_match=221.0.0.0/24&chronological_order=False&max_updates_to_return=1" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
  "seconds": 0.0037958621978759766,
  "bytes": 16678,
  "data": [[1744287050.0, "W", "8.0.10.0/16"]]
}

---

/rib

Retrieve RIB entries for a set of VPs at a given date.

Query Parameters:

• vp_ips (required): Comma-separated list of vantage point IP addresses.
  ⚠️ A maximum of 10 IPs can be provided per query.
• date (required): Timestamp of the RIB snapshot in the iso format YYYY-MM-DDTHH:MM:SS.
  🚀 You can request a RIB snapshot for any point in time — even for vantage points operated by RIS, RouteViews, PCH, or CGTF, which archive RIB snapshots periodically (e.g., every 2 or 8 hours).
• prefix_filter (optional): Comma-separated list of prefix conditions in the form OPERATOR:CIDR. Only entries for prefixes matching these conditions are returned. Operators follow PostgreSQL CIDR semantics, such as:
  • <<:1.0.0.0/8 (prefix contained in)
  • =:2.2.2.2/24 (exact match)- prefix_exact_match (optional): List of prefixes.
• return_aspath (optional): Include AS path in the result. Default is True.
  Set to False to reduce response size and execution time when AS path data is not needed.
• aspath_exact_match (optional): Comma-separated list of AS paths for exact matching. 💡 Use this over aspath_regexp for better performance when exact matching is sufficient.
• aspath_regexp (optional): Regex filter on AS path. Only entries for which the AS patch match the filter will be returned. Internally uses PostgreSQL pattern matching. The expression must not exceed 100 characters for security reasons. Example: ^2914|2914$ matches paths that start or end with 2914.
• return_community (optional): Include BGP communities in the response. Default is True.
  Set to False to reduce response size and improve execution time if community data is not required.
• community_regexp (optional): Regex on BGP community values, using PostgreSQL regex syntax. The expression must not exceed 100 characters for security reasons. Example: 100:10 100:20|100:30 matches entries with communities 100:10 100:20 or 100:30.
• with_as_set (optional): Determines whether AS paths including an AS set should be returned.
  • True (default): AS paths with AS sets are returned; they are represented as strings (e.g., 1234 4534 {13,124} 34).
  • False: AS paths with AS sets are not returned; the returned AS paths (all other AS paths) are a list of integers.

Examples 1:

Retrieve the prefixes observed by vantage points, 1.1.1.1, 2.2.2.2, 3.3.3.3, and 4.4.4.4 on July 31, 2025 at 20:19:19

curl -X GET "http://api.bgproutes.io/rib?vp_ips=1.1.1.1,2.2.2.2,3.3.3.3,4.4.4.4&date=2025-07-31T20:19:19&return_community=False&return_aspath=False" -H "accept: application/json" -H "x-api-key: test-key"

Tip: Excluding AS path and community data can greatly improve query performance in the scenarios where your objective is simply to verify whether a vantage point observes specific prefixes.

Example of output:

{
  "seconds":0.020998001098632812,
  "bytes":229,
  "data":{
    "1.1.1.1":{"1.1.1.0/24":[null,null],"2.2.2.0/24":[null,null]},
    "2.2.2.2":"The vantage point was down at the specified time.",
    "3.3.3.3":{"1.1.1.0/24":[null,null],"2.2.2.0/24":[null,null], "3.3.3.0/24":[null,null]},
    "4.4.4.4":"The vantage point does not exist."
  }
}

Examples 1:

Retrieve the number of entries with has an AS path that has community 10:100 as observed from VPs 1.1.1.1.

curl -X GET "http://api.bgproutes.io/rib?vp_ips=1.1.1.1&date=2025-07-31T20:19:19&community_regexp=10:100&return_count=True" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
  "seconds":0.020998001098632812,
  "bytes":229,
  "data":{
    "1.1.1.1":12,
  }
}

---

/topology

Return the AS-level topology at precise time or day.

Query Parameters:

• vp_ips (required): Comma-separated list of vantage point IP addresses.
  ⚠️ A maximum of 10 IPs can be provided per query.
• date (required): Timestamp used to construct the topology. Two formats are supported:
  • Precise but slower: YYYY-MM-DDTHH:MM:SS — builds the topology using the exact RIB available at that time.
  • Faster but approximate: YYYY-MM-DD — selects a representative RIB from that day to build the topology.
• directed (optional): Whether to return a directed graph. If false (default), the graph is undirected.
• with_aspath (optional): If true, returns the full list of AS paths used to build the topology. Default if False. ⚠️ Enabling this can result in large payloads.
• with_rib (optional): Used only when date is in the format YYYY-MM-DD. If true, AS paths from RIB snapshots collected on that day are included. Default is true.
• with_updates (optional): Also used only when date is in the format YYYY-MM-DD. If true, AS paths from BGP updates received on that day are included. Default is false.
• as_to_ignore: (optional) Comma-separated list of AS numbers to exclude from the topology. These ASes will be removed both from the returned topology graph and from AS paths (if with_aspath is set to True). When an AS is ignored, the ASes immediately before and after it in the path will be connected directly. This option is useful for filtering out ASes such as IXP AS numbers, private ASNs, bogus ASNs, etc. You may enable both with_rib and with_updates, but be aware that doing so increases processing time.
• ignore_private_asns: (optional) Boolean. Ignore privates ASNs, typically those between 64512 and 131071 and those between 4200000000 and 4294967295 (default is False).

Examples 1:

Return the AS-level topology for July 31, 2025 using vantage 1.1.1.1, without AS paths.

curl -X GET "http://api.bgproutes.io/topology?vp_ips=1.1.1.1&date=2025-07-31" -H "accept: application/json" -H "x-api-key: test-key"

Example of output:

{
  "seconds":3.056,
  "bytes":2294456,
  "data":{
    "links":[[1,2],[2,4],.....],
    "aspaths":[]
  }
}

---

For bug reports or feedback, feel free to reach out at contact@bgproutes.io.

Enjoy querying BGP data! 🌐