API Documentation

Interactive REST API for NetCores network analysis

Checking API status...
Base URL: https://netcores.fi.uba.ar/api

Quick Start

The NetCores API provides programmatic access to network analysis functionality. All endpoints return JSON responses with standardized error handling.

Authentication

All read endpoints are public and need no authentication. The two endpoints that start data updates (POST /api/refresh, POST /api/scheduler/update) require Authorization: Bearer <ADMIN_TOKEN> and are disabled on the public server. GET responses carry an ETag and may be cached for an hour; data changes monthly.

Common Response Codes
  • 200 - Success
  • 400 - Bad Request (validation error)
  • 404 - Not Found
  • 304 - Not Modified (your cached copy is current)
  • 401 / 403 - Admin token missing or admin endpoints disabled
  • 500 - Internal Server Error

Check the health status of the NetCores application and data availability.

Response
{ "status": "healthy", "version": "0.2.1", "commit": "515f58c57a1f", "data_status": "available", "timestamp": "2026-09-29T02:10:00.123456", "database": { "status": "healthy", "total_snapshots": 482, "latest_ipv4_date": "2026-09-01", "latest_ipv6_date": "2026-09-01" } }

Get a summary of available data across all IP versions.

Response
{ "ipv4": { "snapshot_count": 45, "date_range": ["2020-01-01", "2024-08-01"], "total_asns": 75000 }, "ipv6": { "snapshot_count": 32, "date_range": ["2020-01-01", "2024-08-01"], "total_asns": 25000 } }

Get k-core trend analysis for a specific ASN over time.

Parameters
Parameter Type Required Description Example
asn integer Yes Autonomous System Number 3356
ip_version string No IP version (ipv4 or ipv6) ipv4
start_date string No Start date (YYYY-MM-DD) 2020-01-01
end_date string No End date (YYYY-MM-DD) 2024-01-01
Example Request
curl "https://netcores.fi.uba.ar/api/trends/3356?ip_version=ipv4&start_date=2020-01-01"
Response
{ "asn": 3356, "ip_version": "ipv4", "date_range": { "start": "2020-01-01", "end": "2024-08-01" }, "trend_data": [ { "date": "2020-01-01", "shell_index": 45, "max_shell_index": 50, "normalized_shell_index": 0.90 } ] }

Get k-core trend analysis for multiple ASNs with comparative data.

Request Body
{ "asns": [3356, 15169, 2906], "ip_version": "ipv4", "start_date": "2020-01-01", "end_date": "2024-01-01" }
Example Request
curl -X POST "https://netcores.fi.uba.ar/api/trends" \ -H "Content-Type: application/json" \ -d '{ "asns": [3356, 15169, 2906], "ip_version": "ipv4" }'
Response
{ "asns": [3356, 15169, 2906], "ip_version": "ipv4", "date_range": { "start": "2020-01-01", "end": "2024-08-01" }, "trend_data": { "3356": [ { "date": "2020-01-01", "shell_index": 45, "max_shell_index": 50, "normalized_shell_index": 0.90 } ], "15169": [...], "2906": [...] } }

Trigger a refresh of AS-relationship data from CAIDA sources.

Admin only. Requires Authorization: Bearer <ADMIN_TOKEN>. On the public server this returns 403 admin_disabled: data updates run automatically every month.
Request Body
{ "ip_versions": ["ipv4", "ipv6"] }
Response
{ "ipv4": { "processed": true, "snapshots_added": 2, "latest_date": "2024-08-01" }, "ipv6": { "processed": true, "snapshots_added": 1, "latest_date": "2024-08-01" } }

Get the current status of the automatic update scheduler.

Response
{ "running": true, "next_run": "2024-09-06T00:00:00Z", "enabled": true, "schedule": "0 0 6 * *" }

Trigger a manual check for new data and update the database if new snapshots are available.

Admin only. Requires Authorization: Bearer <ADMIN_TOKEN>. On the public server this returns 403 admin_disabled: data updates run automatically every month.
Response
{ "triggered": true, "results": { "ipv4": { "checked": true, "updated": false, "new_snapshots": 0, "error": null }, "ipv6": { "checked": true, "updated": true, "new_snapshots": 1, "error": null } }, "timestamp": "2024-08-11T12:00:00Z" }

Get information about available network snapshots in the database.

Parameters
Parameter Type Required Description
ip_version string No Filter by IP version (ipv4 or ipv6)
Response
{ "ipv4": [ { "date": "2024-08-01", "max_shell_index": 50, "unique_asns": 75000 }, { "date": "2024-07-01", "max_shell_index": 49, "unique_asns": 74500 } ], "ipv6": [...] }

For every snapshot: the maximum shell index, how many ASes are in the innermost core (core_size) and how many ASes are in the graph (total_asns).

Example
curl "https://netcores.fi.uba.ar/api/overview?ip_version=ipv4"

ASes in the innermost core of a snapshot. date (YYYY-MM-DD) picks the latest snapshot on or before it; min_normalized (0.5-1.0, default 1.0) widens the list to near-core ASes.

Example
curl "https://netcores.fi.uba.ar/api/core?ip_version=ipv4"

Largest rises and falls in normalized shell index between the latest snapshot and the one months earlier. min_level (default 0.5) ignores ASes that stay below it in both snapshots. status is new or gone when an AS is absent from one snapshot.

Example
curl "https://netcores.fi.uba.ar/api/movers?ip_version=ipv4&months=12&limit=5"

Autocomplete by AS number prefix or name, from CAIDA's AS-to-Organization data plus curated short names.

Example
curl "https://netcores.fi.uba.ar/api/asn/search?q=netflix"

Display name, registry AS name, organization and country for up to 20 ASNs.

Example
curl "https://netcores.fi.uba.ar/api/asn/names?asns=15169,2906"

Common ASN References

Major Transit Providers
  • 3356 - Level3 (now Lumen)
  • 1299 - Telia Carrier
  • 174 - Cogent Communications
  • 2914 - NTT Communications
  • 3257 - GTT Communications
Major Content Providers
  • 714 - Apple
  • 2906 - Netflix
  • 15169 - Google
  • 16509 - Amazon
  • 32934 - Facebook (Meta)
  • 8075 - Microsoft