# Mac Daily — dataset CSV data dictionary

Mac Daily data is licensed CC BY 4.0 (<https://creativecommons.org/licenses/by/4.0/>) — reuse with attribution to Mac Daily. Files are UTF-8 with a leading byte-order mark (for Excel compatibility), RFC 4180, CRLF line endings. Dates are ISO 8601. Numbers use a dot decimal separator and no thousands separator. Text cells that begin with `=`, `+`, `-` or `@` carry a leading apostrophe so spreadsheet applications render them as text instead of evaluating them as formulas.

Exception: original UN Comtrade observations retain their upstream terms (https://uncomtrade.org/docs/policy-on-comtrade-data-use/). Attribution to Mac Daily does not grant redistribution rights to upstream data. Check each dataset’s licence metadata.

Every figure carries an explicit `basis` and, where applicable, a moisture percentage — sources disagree because they mix bases, so a value without its basis is not data.

## Figure CSVs (`/{locale}/macadamia-index/countries/{iso}.csv` and `/{locale}/macadamia-index/data/{metric}.csv`)

| Column | Description |
| --- | --- |
| `id` | Stable figure identifier. |
| `metric` | What is measured (production, export, price, …). |
| `value` | The reported numeric value in `unit`. |
| `unit` | Unit of `value` (t, kg, USD_per_kg, …). |
| `basis` | Weight basis: NIS, DNIS, kernel, not_applicable or unknown. A tonnage without a basis is not data. |
| `moisture_pct` | Moisture percentage (NIS/DNIS only), else empty. |
| `country` | ISO 3166-1 alpha-2 country, or empty for a global figure. |
| `region` | Region label, or empty. |
| `crop_year` | Crop year the figure describes. |
| `value_type` | actual, forecast, estimate or revised. |
| `kernel_style` | Kernel style for price rows (S1, S4L, halves, pieces, other) — styles are independent series; else empty. Without it, an S1 and a halves quote are indistinguishable in the download. |
| `hs_code` | HS code for trade rows (0802.61 in-shell, 0802.62 shelled), else empty. |
| `partner_country` | Partner ISO 3166-1 alpha-2 for a bilateral trade row; empty = the reporter’s total to the World. A World total is the sum of its corridors — never sum rows across different partner scopes. |
| `currency` | ISO 4217 currency for price/fx rows, else empty. |
| `source_org` | Publishing organisation of the figure. |
| `source_url` | Canonical source URL for the figure. |
| `source_published_at` | Date the source published the figure (ISO 8601). |
| `retrieved_at` | Date Mac Daily retrieved the figure (ISO 8601). |
| `confidence` | high, medium, low, or empty. |
| `status` | active or superseded (in-season revisions). |
| `normalized_dnis35` | Value normalised to DNIS at 3.5% moisture, when computable, else empty. |
| `normalized_kernel_equiv` | Kernel-equivalent value, when a ratified conversion exists, else empty. |
| `conversion_version` | Conversion-ratio version stamped on the figure, or empty. |

## Trade corridors (`/{locale}/macadamia-index/trade/{from}-{to}.csv`)

| Column | Description |
| --- | --- |
| `reporter` | Reporting country ISO 3166-1 alpha-2; the importer for an import flow. |
| `partner` | Partner country ISO 3166-1 alpha-2; the supplier for an import flow. |
| `flow` | export or import. |
| `hs_code` | HS code — 0802.61 in-shell, 0802.62 shelled. In-shell and shelled are never merged. |
| `value` | Reported trade value in `unit`. |
| `unit` | Unit of `value`. |
| `basis` | Weight basis of the figure. |
| `moisture_pct` | Moisture percentage (NIS/DNIS only), else empty. |
| `crop_year` | Crop year the flow describes. |
| `value_type` | actual, forecast, estimate or revised. |
| `source_org` | Publishing organisation. |
| `source_url` | Canonical source URL. |
| `source_published_at` | Source publication date (ISO 8601). |
| `retrieved_at` | Retrieval date (ISO 8601). |
| `confidence` | high, medium, low, or empty. |
| `calendar_period` | Exact customs period, YYYY or YYYY-MM; not a harvest season. |
| `frequency` | A = annual, M = monthly. Never add annual and monthly observations together. |
| `trade_value_usd` | Reported primary customs trade value in current USD; not a price quote. |
| `fob_value_usd` | Reported FOB value in USD when supplied. |
| `cif_value_usd` | Reported CIF value in USD when supplied. |
| `weight_estimated` | Whether Comtrade flags the weight as estimated. |