Use the index.

country is an uppercase ISO code. region is a catalog jurisdiction ID and requires its matching country. plan defaults to basket-v1. Without a country, the index and CSV return the default jurisdiction for every country.

date=YYYY-MM-DD requests a recorded index snapshot. Future dates are rejected. The current ranking endpoints reject historical dates and price scenarios. The all-paid-plans median (basket-all-paid-v1) is a separate comparison measure, not the fixed official three-plan basket.

Errors: invalid, mismatched or unsupported queries return 400; an out-of-scope country or absent recorded snapshot returns 404; temporarily unavailable recorded history or revisions return 503. Check the HTTP status before parsing data. Do not convert an error into zero hours.

Current dataset reads use a 60-second shared-cache window. A saved published response keeps original verification dates and declares its delivery mode. These are reference observations with editorial review, not a guaranteed real-time feed.

Each fixed revision JSON or CSV response preserves its own immutable bytes and uses immutable response caching. Successful GET requests return the full body with HTTP 200 and X-Content-SHA256, a SHA-256 checksum of the decoded, final UTF-8 response body. Requests with If-None-Match also return a full 200 response rather than 304; no ETag is issued. Save the response and its checksum, or compare X-Content-SHA256 with a saved copy when needed.

The stored fingerprint describes the original source result and is not a file checksum. History lists the latest revision per day; retained earlier revisions remain addressable by their snapshot IDs. Missing or unavailable recorded data never triggers a recalculation from current inputs.

The public endpoints support cross-origin GET and HEAD without credentials. Authentication and internal routes are outside this contract; write requests are not allowed.

const response = await fetch("https://www.intelligence-hours.org/api/v1/index?country=JP&region=JP-13&plan=basket-v1");
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const payload = await response.json();
const row = payload.data[0];
if (!row) throw new Error('No result returned');
const saved = payload.meta.dataDelivery?.mode === 'snapshot';
if (row.hours === null || row.status === 'unavailable') {
  console.warn(row.reason ?? 'Work time unavailable');
} else {
  // Preserve reference/stale labels and the saved-data notice.
  console.log({ hours: row.hours, status: row.status, saved,
    jurisdiction: row.jurisdictionName, asOf: row.asOf,
    wageBasis: row.wageBasis, dataDelivery: payload.meta.dataDelivery,
    sources: row.sources, observationIds: row.observationIds });
}

import json
from urllib.request import urlopen

# HTTP errors raise an exception; do not turn them into zero hours.
with urlopen("https://www.intelligence-hours.org/api/v1/index?country=JP&region=JP-13&plan=basket-v1", timeout=20) as response:
    payload = json.load(response)
row = payload["data"][0]
delivery = payload["meta"].get("dataDelivery", {})
if row["hours"] is None or row["status"] == "unavailable":
    print(row.get("reason") or "Work time unavailable")
else:
    print({"hours": row["hours"], "status": row["status"],
           "saved": delivery.get("mode") == "snapshot",
           "jurisdiction": row["jurisdictionName"], "asOf": row["asOf"],
           "wageBasis": row["wageBasis"], "dataDelivery": delivery,
           "sources": row["sources"], "observationIds": row["observationIds"]})