# Hats Network Open Data — Global Latency Measurements

Public measurement data from the **Hats Network Inc.** global backbone
([AS203314](https://bgp.tools/as/203314)), a hybrid eyeball ISP and transit
provider operating 20 points of presence across Europe, North America, South
America, Asia-Pacific, and Africa.

All datasets in this repository are produced from **actual ICMP echo
measurements** collected on the production network. Every directed pair of
PoPs is probed once per measurement round with 50 echo requests at a 100 ms
interval; round-trip times (RTT) are published as raw per-sample series
together with per-pair summary statistics.

- **Home page**: [hatsnet.io/opendata](https://hatsnet.io/opendata/)
- **Methodology**: [theoretical latency verification](https://hatsnet.io/docs/network/latency/theoretical-latency-verification)
- **Interactive matrix**: [global latency matrix](https://hatsnet.io/docs/network/latency)

## Datasets

| Dataset           | Path                 | Description                                                            |
| ----------------- | -------------------- | ---------------------------------------------------------------------- |
| `hatsnet-latency` | `/opendata/latency/` | Inter-PoP ICMP RTT measurements (342+ directed pairs, 50 samples each) |

## Directory layout

```text
/opendata/
├── README.md                     # source document for this rendered preview
├── latency/
│   ├── LICENSE.txt               # CC BY 4.0 full text
│   ├── datapackage.json          # Frictionless Data Package descriptor
│   ├── manifest.json             # pointer to the current release
│   ├── vYYYYMMDD/                # immutable dated release (never modified)
│   │   ├── manifest.json         # machine-readable file manifest (sha256)
│   │   ├── SHA256SUMS            # GNU sha256sum format, `sha256sum -c` clean
│   │   ├── matrix.{csv,json,yaml}.zst / .gz   # per-pair summary statistics
│   │   ├── pings.{csv,json,yaml}.zst / .gz    # raw per-sample long table
│   │   └── pairs/                             # per-pair files, uncompressed
│   │       ├── ams-hkg.pings.csv
│   │       ├── ams-hkg.pings.json
│   │       └── ams-hkg.pings.yaml
│   └── latest/                   # current release (mirror of vYYYYMMDD)
```

### Versioning

- Releases are **dated and immutable**: once published, a `vYYYYMMDD/`
  directory is never modified. Corrections ship as a new dated release.
- `latest/` always mirrors the most recent release.
- `manifest.json` carries a `schema_version` field; breaking schema changes
  bump it and move to a new series directory.

## File formats

Each release publishes the same content in **CSV**, **JSON**, and **YAML**.
Aggregate files (covering all pairs) are compressed with **zstd** (`.zst`,
level 3) and additionally with **gzip** (`.gz`) for toolchains without zstd
support. Per-pair files under `pairs/` are small and published uncompressed,
ready to use directly in a browser or script.

### Aggregates

- `matrix.*` — one row per directed pair:
  `from, to, round_id, rtt_avg, rtt_min, rtt_max, rtt_stdev, jitter_ms, packet_loss_percent`
  (all values in milliseconds; `jitter_ms` is the mean absolute difference of
  consecutive samples; `packet_loss_percent` is the share of unanswered echo
  requests).
- `pings.*` — raw measurement long table:
  `from, to, round_id, seq, offset_ms, rtt_ms`
  (`seq` is the 1-based sample index, `offset_ms = (seq - 1) * 100`).

### Measurement rounds

`round_id` is the UTC start time shared by every sample in one publication
round. The same value appears in CSV, JSON, YAML, manifests, and documentation
pages so records from one round can be joined directly.

### Decompression examples

```bash
# zstd
zstd -d matrix.csv.zst        # → matrix.csv
zstd -dc pings.csv.zst | head

# gzip
gzip -dk matrix.csv.gz        # → matrix.csv
```

```python
import pandas as pd

# pandas ≥ 2.0 reads .zst directly
df = pd.read_csv("https://hatsnet.io/opendata/latency/latest/matrix.csv.zst")
```

## Integrity

Every release directory contains `SHA256SUMS` (GNU format) covering all files
in that directory, and `manifest.json` with per-file `size` / `sha256` / `rows`:

```bash
cd v20260806 && sha256sum -c SHA256SUMS
```

## Update frequency

A new full release is published **daily, around 03:47–04:00 UTC**, in lockstep
with the on-site latency matrix refresh. Releases are skipped automatically
when the underlying measurements have not changed.

## License

**[Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/)**
— see `latency/LICENSE.txt` for the full legal text. You are free to share and
adapt the data, including for commercial purposes, as long as you give
appropriate credit.

## Citation

BibTeX:

```bibtex
@misc{hatsnet_latency_dataset,
  author       = {{Hats Network Inc.}},
  title        = {Hats Network Global Latency Measurements (AS203314)},
  howpublished = {\url{https://hatsnet.io/opendata/latency/}},
  year         = {2026},
  note         = {Daily ICMP echo RTT measurements, accessed YYYY-MM-DDTHH:mm:ssZ},
}
```

APA:

> Hats Network Inc. (2026). _Hats Network Global Latency Measurements
> (AS203314)_ [Data set]. https://hatsnet.io/opendata/latency/

## Contact

- Data & research inquiries: [info@hatsnet.io](mailto:info@hatsnet.io)
- Network operations: [noc@hatsnet.io](mailto:noc@hatsnet.io)