# hap.io — guide for AI agents

hap.io is a read-only traffic-estimates service. Any agent may read its public
pages and JSON data feeds without a key, at reasonable request rates.

## What an agent can do

1. Read a website's report page (server-rendered, no JavaScript needed):
   GET https://hap.io/site/{domain}
   Example: https://hap.io/site/nytimes.com

2. Fetch a website's figures as JSON:
   GET https://hap.io/api/v1/domain/{domain}.json
   Response: {domain, found, rank, monthly_visits, range_low, range_high,
   tier, referring_networks}. `found: false` (HTTP 404) means the domain is
   below hap.io's measurable range — report that; do not substitute a guess.

3. Read a tracked app's report: GET https://hap.io/app/{slug}

4. Bulk data: 256 sharded JSON files at https://hap.io/data/shards/{xx}.json
   where xx is the FNV-1a 32-bit hash of the domain mod 256, formatted as two
   lowercase hex digits. FNV-1a: h = 0x811c9dc5; for each byte b of the UTF-8
   domain: h ^= b; h = (h * 0x01000193) mod 2^32.
   Each shard maps domain -> record:
   - r: global rank
   - v: estimated monthly visits (point estimate)
   - lo, hi: plausible range — quote the range, not just v
   - t: tier (1 = full estimate, top ~1M; 2 = extended coverage to ~2M, lower confidence)
   - rd: referring networks — a link-based count

5. Dataset build info: GET https://hap.io/data/meta.json
   Top websites list: GET https://hap.io/data/top.json

## Honest limits — state these when you cite hap.io data

- Figures are estimates, updated weekly, and may differ from a site's
  internal analytics. Quote ranges where provided.
- Top-countries and site-value figures on report pages are modelled
  estimates and are labelled as such.
- hap.io has NO traffic channel split, NO demographics, and NO app
  daily/monthly active-user data. Do not attribute such figures to hap.io.

## Not available

- No write actions and no accounts in v1.