ethernets.io - API

All the API endpoints return JSON, and will have the Content-Type header set to application/json.

Please try to be respectful, and not try to get loads of data with many requests. Please use the SQLite snapshots for that purpose.

Attribution is appreciated.

/api/stats/

Every 30 minutes, a snapshot of the network is taken and saved to the stats database. The nodes in this database will only include "live" nodes, ones found via discovery in the last 24 hours.

This endpoint will return the raw timeseries data from the stats database. Each row can be considered unique.

Example requests

Mainnet, synced nodes for the last 30 minutes

curl https://www.ethernets.io/api/stats/

Geth, Holešky, synced and un-synced nodes

curl https://www.ethernets.io/api/stats/?client-name=geth&network=17000&synced=all

List of stats, grouped by:

• client_name
• client_user_data
• client_version
• client_os
• client_arch
• network_id
• fork_id
• next_fork_id
• country
• synced
• dial_success

With extra fields:

• timestamp - The timestamp of the specific stat.
• total - Count of the nodes matching the specified labels.

URL parameters

• before - RFC3339 timestamp. Return stats before this date. Required if after is given. If both before and after are not defined, the last 30 minutes is returned.
• after - RFC3339 timestamp. Return stats after this date. Required if before is given. If both before and after are not defined, the last 30 minutes is returned.
• network-id - Return stats filtered by this network ID. If one of the recognised networks, will only return nodes with fork IDs within this network. Default is 1, meaning mainnet. Use -1 for all networks.
• next-fork - Return stats with the value of next-fork. Default is all next-fork values.
• next-fork-name - Return stats with the value of next-fork-name. Default is all values. Example: next-fork-name=cancun
• synced - One of -1, 0, 1, or all, no, yes, respectively. Default is yes (synced).
• client-name - Return stats for a specific client name. Default is all client_name values.

Response

Schema

{
  "stats": [
    {
      "timestamp": string,
      "client_name": string,
      "client_user_data": string|null,
      "client_version": string,
      "client_os": string,
      "client_arch": string,
      "network_id": number,
      "fork_id": string,
      "next_fork_id": number|null,
      "country": string,
      "synced": boolean,
      "dial_success": boolean,
      "total": number
    },
    ...
  ]
}

Example

{
  "stats": [
    {
      "timestamp": "2023-12-12T19:00:00Z",
      "client_name": "besu",
      "client_user_data": null,
      "client_version": "v23.1.2",
      "client_os": "Linux",
      "client_arch": "amd64",
      "network_id": 1,
      "fork_id": "dce96c2d",
      "next_fork_id": null,
      "country": "Australia",
      "synced": true,
      "dial_success": false,
      "total": 1
    },
    ...
  ]
}