# Harpd Research Dataset README

> Human-readable README for the Harpd research reports at https://harpd.com/research/.

## What it is

Harpd Research publishes closed monthly reports derived from Harpd Rank data.
Research families track specific themes (for example the AI tools index or the
developer tools index); each family has its own slug and description. Reports are
organized as /research/{family}/{year}/{month}/ and cover a closed UTC month.

## How it is generated

Every figure in a research report is derived from a closed monthly archive
snapshot (/api/rank/archive/monthly/{key}), or from diffing the previous month's
snapshot when the report discusses movement or new entrants. Nothing is authored
by hand and no number is estimated. A page is only published when its period is
closed and the family-scoped snapshot contains enough approved listings to be
meaningful.

## Update frequency

Monthly. A snapshot is written once, after the month closes, and is never edited —
historical reports stay reproducible forever.

## Schema

Each report resolves to its underlying evidence and data timestamp. The
machine-readable form is the evidence graph (https://harpd.com/data/evidence.json),
where every published claim is linked to the dataset, methodology, source and
timestamp that support it.

## License

CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/

## Citation

Research claims must resolve to evidence. Cite the report URL together with the
dataset and methodology that support each claim; never cite a number without its
underlying dataset. The citation and methodology policy lives at
https://harpd.com/research/methodology/.

## Limitations

- Research measures closed monthly snapshots of the Harpd Rank board, not the live board; positions are final at month close.
- Claims in research must resolve to a registered dataset and methodology. A claim that does not is unsupported and will not be published as a fact.
- Harpd Rank Points are promotional placement, not an editorial quality score; research does not present them as a measurement of quality.

## Methodology

The methodology is documented at https://harpd.com/research/methodology/.

## Reproduction

1. Pick a published report at https://harpd.com/research/{family}/{year}/{month}/.
2. Fetch the closed monthly snapshot for that period via /api/rank/archive/monthly/{key}.
3. Every claim in the report resolves to a dataset, methodology and timestamp in the evidence graph (https://harpd.com/data/evidence.json), so each number can be re-derived from the same immutable snapshot data.

## Attribution

Source: Harpd
Data licensed under CC BY 4.0: https://creativecommons.org/licenses/by/4.0/
Canonical page: https://harpd.com/research/