Doc: AMR oil-trade complete data dictionary
Status: Fixed source edition, essential values complete
Owner: American Mineral Registry
Last verified: 2026-11-14
Depends on: evidence-contract.json, pinned EIA source CSVs and analysis.py

Run python 3 analysis.py and python 3 figures.py from the extracted bundle. Programs resolve their own folder, require only Python standard library, make no network request and do not modify source files.

## Scope, units and sign

The annual domain is 1949 through 2025,77 complete years. The monthly domain is January 1977 throughDecember 2025,588 complete observations. All 2026 partial estimates are excluded.29 unreported early crude-export cells do not become zero; the monthly domain begins after them.

Core quantities are thousand barrels per day. Divide by 1000 to obtain million barrels per day. A positive net-import value means imports exceed exports; a negative value means net exports. All derived values reproduce rounded source inputs and do not claim greater physical measurement accuracy. Annual values use producer annual rows rather than equally weighted monthly rates.

Crude includes lease condensate. Non-crude is the same-period total petroleum value minus crude, separately for each direction. It includes a broad collection of other liquids and products, not only finished refinery fuels. Source classifications change historically, including specified ethanol, biofuel and blending-component additions. This is the published evolving series, not a constant-product-basket reconstruction. Geography is 50 states and DC; source notes include shipments to and receipts from U.S. territories.

Calculated net totals can differ from the directly published independently rounded net series by up to 0.001 thousand barrels per day in the selected panel. Both are retained; annual-table classifications use unrounded calculation from gross values. No country ranking, exact foreign share of consumption, causal policy effect or energy-independence score is inferred.

## annual-net-trade-change-bridge.csv

76 complete rows.

| Field | Definition |
| --- | --- |
| previous_year | Previous adjacent calendar year in the same pinned source vintage. |
| year | Calendar observation year, not article update year. |
| change_crude_imports_effect_kbd | Thousand barrels per day, change crude imports effect. Export increases reduce net imports. Accounting contribution, not causal attribution. |
| change_crude_exports_effect_kbd | Thousand barrels per day, change crude exports effect. Export increases reduce net imports. Accounting contribution, not causal attribution. |
| change_noncrude_imports_effect_kbd | Thousand barrels per day, change noncrude imports effect. Export increases reduce net imports. Accounting contribution, not causal attribution. |
| change_noncrude_exports_effect_kbd | Thousand barrels per day, change noncrude exports effect. Export increases reduce net imports. Accounting contribution, not causal attribution. |
| change_total_net_imports_kbd | Thousand barrels per day, change total net imports. Positive is net imports; negative is net exports. |
| interpretation | Material accounting qualification, retained with data. |
| import_source | EIA table 3.3 B, original gross import inputs. |
| export_source | EIA table 3.3 E, original gross export inputs. |

## annual-status-and-gross-flow-ratios.csv

77 complete rows.

| Field | Definition |
| --- | --- |
| year | Calendar observation year, not article update year. |
| crude_trade_status | Sign of gross crude imports minus crude exports. |
| noncrude_trade_status | Sign of non-crude residual imports minus residual exports. |
| petroleum_trade_status | Sign of gross total petroleum imports minus gross total exports. |
| total_exports_as_share_of_total_imports_percent | Percentage with the exact named gross-flow or total-change denominator. total exports as share of total imports. |
| crude_share_of_petroleum_imports_percent | Percentage with the exact named gross-flow or total-change denominator. crude share of petroleum imports. |
| crude_share_of_petroleum_exports_percent | Percentage with the exact named gross-flow or total-change denominator. crude share of petroleum exports. |
| noncrude_share_of_petroleum_exports_percent | Percentage with the exact named gross-flow or total-change denominator. noncrude share of petroleum exports. |
| source_url | Primary source for the specified observations. Some derived fields require the additional source URL too. |
| additional_source_url | Additional original producer input needed for the calculation. |

## annual-trade-balances-1949-2025.csv

77 complete rows.

| Field | Definition |
| --- | --- |
| period | Calendar year for annual rows, or YYYY-MM for monthly rows. |
| frequency | Annual source row or calendar-month source row. |
| crude_imports_kbd | Thousand barrels per day, crude imports. |
| crude_exports_kbd | Thousand barrels per day, crude exports. |
| noncrude_imports_kbd | Thousand barrels per day, noncrude imports. |
| noncrude_exports_kbd | Thousand barrels per day, noncrude exports. |
| petroleum_imports_kbd | Thousand barrels per day, petroleum imports. |
| petroleum_exports_kbd | Thousand barrels per day, petroleum exports. |
| crude_net_imports_kbd | Thousand barrels per day, crude net imports. Positive is net imports; negative is net exports. |
| noncrude_net_imports_kbd | Thousand barrels per day, noncrude net imports. Positive is net imports; negative is net exports. |
| petroleum_net_imports_calculated_kbd | Thousand barrels per day, petroleum net imports calculated. Positive is net imports; negative is net exports. |
| petroleum_net_imports_published_kbd | Thousand barrels per day, petroleum net imports published. Positive is net imports; negative is net exports. |
| published_net_rounding_difference_kbd | Calculated total net imports minus published net imports, thousand barrels per day; separate source-rounding reconciliation. |
| unit | All core flow levels use thousand barrels per day, a rate, not a stored volume. |
| source_vintage | The exact October 2026 Monthly Energy Review release used for all numerical inputs. |
| import_source | EIA table 3.3 B, original gross import inputs. |
| export_source | EIA table 3.3 E, original gross export inputs. |
| published_net_source | EIA table 3.3 A, independently rounded published total petroleum net imports. |

## complete-year-monthly-trade-status-counts.csv

49 complete rows.

| Field | Definition |
| --- | --- |
| year | Calendar observation year, not article update year. |
| complete_months | Twelve verified matched monthly observations for this complete calendar year. |
| net_crude_importer_months | Count of matched months satisfying the named sign condition; complete calendar-year denominator 12. |
| net_noncrude_exporter_months | Count of matched months satisfying the named sign condition; complete calendar-year denominator 12. |
| net_total_petroleum_exporter_months | Count of matched months satisfying the named sign condition; complete calendar-year denominator 12. |
| annual_total_petroleum_net_imports_kbd | Thousand barrels per day, annual total petroleum net imports. Positive is net imports; negative is net exports. |
| source_url | Primary source for the specified observations. Some derived fields require the additional source URL too. |

## fixed-year-category-bridge-2025.csv

3 complete rows.

| Field | Definition |
| --- | --- |
| year | Calendar observation year, not article update year. |
| category | Crude including lease condensate, non-crude residual or total petroleum. |
| imports_kbd | Thousand barrels per day, imports. |
| exports_kbd | Thousand barrels per day, exports. |
| net_imports_kbd | Thousand barrels per day, net imports. Positive is net imports; negative is net exports. |
| scope | Geographic and category coverage that accompanies the comparison. |
| import_source | EIA table 3.3 B, original gross import inputs. |
| export_source | EIA table 3.3 E, original gross export inputs. |

## monthly-trade-balances-1977-2025.csv

588 complete rows.

| Field | Definition |
| --- | --- |
| period | Calendar year for annual rows, or YYYY-MM for monthly rows. |
| frequency | Annual source row or calendar-month source row. |
| crude_imports_kbd | Thousand barrels per day, crude imports. |
| crude_exports_kbd | Thousand barrels per day, crude exports. |
| noncrude_imports_kbd | Thousand barrels per day, noncrude imports. |
| noncrude_exports_kbd | Thousand barrels per day, noncrude exports. |
| petroleum_imports_kbd | Thousand barrels per day, petroleum imports. |
| petroleum_exports_kbd | Thousand barrels per day, petroleum exports. |
| crude_net_imports_kbd | Thousand barrels per day, crude net imports. Positive is net imports; negative is net exports. |
| noncrude_net_imports_kbd | Thousand barrels per day, noncrude net imports. Positive is net imports; negative is net exports. |
| petroleum_net_imports_calculated_kbd | Thousand barrels per day, petroleum net imports calculated. Positive is net imports; negative is net exports. |
| petroleum_net_imports_published_kbd | Thousand barrels per day, petroleum net imports published. Positive is net imports; negative is net exports. |
| published_net_rounding_difference_kbd | Calculated total net imports minus published net imports, thousand barrels per day; separate source-rounding reconciliation. |
| unit | All core flow levels use thousand barrels per day, a rate, not a stored volume. |
| source_vintage | The exact October 2026 Monthly Energy Review release used for all numerical inputs. |
| import_source | EIA table 3.3 B, original gross import inputs. |
| export_source | EIA table 3.3 E, original gross export inputs. |
| published_net_source | EIA table 3.3 A, independently rounded published total petroleum net imports. |

## net-trade-reduction-contributions-2005-2025.csv

4 complete rows.

| Field | Definition |
| --- | --- |
| component | One of the four gross-flow changes making up the fixed 2005 to 2025 bridge. |
| start_year | 2005, the observed net-import peak in this fixed complete panel. |
| end_year | 2025, final complete observation year. |
| start_gross_flow_kbd | Thousand barrels per day, start gross flow. |
| end_gross_flow_kbd | Thousand barrels per day, end gross flow. |
| effect_on_net_imports_kbd | Thousand barrels per day, effect on net imports. Positive is net imports; negative is net exports. Export increases reduce net imports. Accounting contribution, not causal attribution. |
| share_of_total_net_import_reduction_percent | Percentage with the exact named gross-flow or total-change denominator. share of total net import reduction. |
| interpretation | Material accounting qualification, retained with data. |
| import_source | EIA table 3.3 B, original gross import inputs. |
| export_source | EIA table 3.3 E, original gross export inputs. |

## used-source-observations.csv

3325 complete rows.

| Field | Definition |
| --- | --- |
| msn | Original EIA series identifier. |
| source_period | Original EIA YYYYMM code; month 13 identifies the annual row, not a thirteenth month. |
| raw_value | Original source decimal string, without assigning zeros to nonnumeric entries. |
| description | Original EIA series description. |
| unit | All core flow levels use thousand barrels per day, a rate, not a stored volume. |
| source_url | Primary source for the specified observations. Some derived fields require the additional source URL too. |

## Source integrity and reuse

Original files and SHA 256 values are in sources/download-receipts.json. Printed table definitions and publication context are separately archived. The source-cell file is a provenance trace, not a separate independent dataset. Source estimates and revisions retain their limitations.

AMR calculations and original figures: CC BY 4.0. Preserve original EIA attribution and applicable source terms.
