# 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][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
    },
    ...
  ]
}

[snapshots]: https://www.ethernets.io/snapshots/