Territory Currency Rules Lookup for Data Pipelines

Enrich commerce and LLM datasets with CLDR tender currency validity and precision rules for country/territory codes at an explicit date.

Build status: implementation and unit/live tests are present. Python tests, a real local actor run and the required apify validate-schema command remain unverified because this environment denies process launch. Four JSON schemas passed checks against the installed official Apify schema definitions; see evidence/schema-validation.json. This draft requires execution checks before publication.

What it returns

One flat row per active tender currency interval. Concurrent currencies stay in CLDR source order: Bhutan can return BTN and INR, Panama PAB and USD. Explicitly non-tender entries, such as USN, CHE and CHW, are excluded. Start/end dates are inclusive calendar dates; missing bounds remain null.

Field	Meaning
status	ok, error or no_match
territory	Normalized two-letter CLDR territory code; null for invalid input
currency / tender	Tender currency code / true on success; null on errors and no matches
asOf	Explicit input date in YYYY-MM-DD
validFrom / validTo	CLDR interval bounds; null means the source omits that bound
digits / rounding	Standard fraction digits and raw CLDR rounding units
roundingIncrement	Decimal-string standard increment in major currency units
cashDigits / cashRounding	Cash fraction digits and raw CLDR cash-rounding units
cashRoundingIncrement	Decimal-string cash increment: CHF/CAD 5 units at 2 digits gives "0.05"
fractionSource	Currency code or DEFAULT when the currency has no override
cldrVersion	Version reported by the fetched JSON
sourceUrl / sourceSha256 / sourceFetchedAt	Official URL, content digest and UTC fetch time
inputTerritory / errorCode / error	Diagnostics on error/no-match rows

USD and TRY use CLDR DEFAULT fractions. Missing cashDigits inherits effective standard digits; missing cashRounding inherits effective standard rounding. Increment "0" means no additional rounding increment, while digits still controls precision. Fractions reflect the fetched snapshot, not historical fraction-rule versions at asOf. This actor supplies rules rather than converted amounts.

Input example

{"territories":["US","TR","JP"],"asOf":"2026-10-06","maxItems":3}

asOf is mandatory; the current date is never substituted. Lowercase and whitespace are normalized and valid duplicate codes are removed. Use two-letter codes, not names or three-letter codes. Historical territory codes are accepted when present in CLDR.

Output example

This is an illustration derived from the fetched official CLDR response. It is not verified Python actor-run output. sample_output.json holds three full example rows; sample_output.provenance.json records this limitation.

{"status":"ok","territory":"US","currency":"USD","tender":true,"asOf":"2026-10-06","validFrom":"1792-01-01","validTo":null,"digits":2,"rounding":0,"roundingIncrement":"0","cashDigits":2,"cashRounding":0,"cashRoundingIncrement":"0","fractionSource":"DEFAULT","cldrVersion":"48"}

Pricing

Proposed currency_rule: USD 0.0002 per successful currency row (USD 0.20 per 1000). Concurrent currencies are separate rows. Errors/no-match rows do not trigger this event. No start fee is proposed. The dated Store comparison and its limitations are in PRICING.md; the owner sets actual published pricing.

Limits and failure handling

• Up to 10000 input items. maxItems defaults to 1000 and accepts 1–10000; successes, errors and no-match rows share the cap. A small cap can truncate a territory's concurrent currencies. RUN_SUMMARY records truncation.
• One cached official currencyData.json snapshot per run. Invalid-only input does not fetch it. Network and result-write concurrency are fixed at one.
• Each request has a 30-second timeout. Network failures, HTTP 408/429 and 5xx responses receive at most three attempts, with 0.5- and 1-second backoff. Permanent HTTP/data errors are cached for the run.
• Invalid/unknown codes, unavailable data and malformed territory records produce per-item errors. A known territory without an active tender interval produces no_match. Empty/missing territories, missing/invalid asOf and invalid maxItems fail the run clearly.
• The official main-branch source is mutable. Version, digest and fetch time identify the snapshot. There is no stale cross-run cache or automatic alternate-source fallback.
• Date-only filtering does not model intraday timezone transitions. Historical availability is limited to CLDR intervals; missing data is not filled with assumptions.

No FX prices, economic indicators, holiday calendar or customer addresses are returned.

Local verification

Use the existing shared environment; do not install into it. Runtime packages are already installed (Apify 4.0.2 and httpx 0.28.1 observed locally). These commands remain pending because process launch was denied in this build session.

& C:/GritWork/earn/.venv/Scripts/python -m pytest tests -q -m 'not live'
& C:/GritWork/earn/.venv/Scripts/python -m pytest tests/test_live.py -q -m live
apify validate-schema
$env:APIFY_LOCAL_STORAGE_DIR = 'C:/GritWork/earn/actors/territory-currency-lookup/storage'
& C:/GritWork/earn/.venv/Scripts/python -m src

Run from the actor directory. Exact prefill is saved in storage/key_value_stores/default/INPUT.json. After a successful local run, replace the illustrative sample with generated default-dataset rows (at most 20), remove illustration status and record elapsed time. Offline tests use tests/fixtures/currencyData.json; the network smoke test is marked live.

FAQ

Does asOf select historical fraction digits? It selects historical currency validity intervals. Fractions always come from the fetched CLDR snapshot.

Why are there multiple rows for a territory? CLDR records concurrent tender currencies and transition overlaps. They are retained until maxItems or the spending limit stops output.

Why is Antarctica no_match? Its CLDR XXX entry is non-tender and excluded.

What does zero cash increment mean? Apply cashDigits precision; the source defines no additional cash-rounding increment. It does not mean unlimited decimal places.

Is it an exchange-rate service? It supplies metadata and formatting rules, without exchange prices or money conversions.

Use with AI agents / MCP

Call this Actor through an existing Apify Actor integration or Apify MCP tool with explicit territories, asOf and maxItems. Join ok rows to commerce/LLM datasets by territory and currency; branch separately on error/no_match. Preserve multiple rows for concurrent currencies. The output schema links to default-dataset items. This package does not create a standalone MCP server.

Official source and license

Unicode CLDR currencyData.json and Unicode LDML supplemental currency data. The saved fixture uses tests/fixtures/CLDR-LICENSE.txt; provenance is in tests/fixtures/provenance.json.