About the Data
Commodity balances show the balance of staple foods. The purpose of this domain is to show the consumption, import, and export of these staple foods for each country.
There are two types of Data Source Documents for the Commodity Balance Sheet domain:
Estimated source document type: contains commodity balance estimates that are usually calculated at the beginning of the season.
Final document type: contains actual data available after the end of the period. All historical data series fall under the final document type.
Data series under both document types are available for users and not overwritten. It is important for users who are uploading Commodity Balance Sheet data to distinguish between estimated and final Data Source Document types.
The Hub uploads Historical Commodity Balance Sheet data. If users have questions about this domain or run into issues with uploading or exporting data, please submit a helpdesk ticket with a detailed description of the issue and the path taken to arrive at the issue.
Data Upload Process
Preparing Data for Upload
Each file should contain the following columns or their equivalent names at a minimum:
Country
Item (Indicator)
Crop (Commodity)
Data Source Document
Values (periods as one column or multiple periods/columns)
Indicators and crop names should be standardized, meaning it is recommended to stick to the names used in the previous periods if possible.
A file may contain other columns; if so, they can still be loaded as long as the required fields above are included.
If the unit type is not specified, the default unit type will be used:
1000 t for weight units (indicators like Net Supply, Export, Requirements etc.)
Percent for indicators Self-Sufficiency and Stock to Use
Person for Population indicator
1 kg for Consumption per capita per year
Importing Commodity Balance Sheet Data
Go to Dataseries Management > Commodity Balances > Commodity Balances.
Click Import Commodity Balances.
Click Choose File and select your spreadsheet to load the file.
Load the same file from Step 1 into the Commodity Balance Value screen. Select: Dataseries Management > Data Points > Commodity Balance Value. Utilizing the same file in Step 1, click the Import Commodity Balance Values button and upload the file in the appropriate format. Click Submit and the file will be in draft status.
Accessing Commodity Balance Sheet Data
There are four endpoints that allow retrieving Commodity Balance data:
https://fdw.fews.net/api/commoditybalance/ returns data series.
https://fdw.fews.net/api/commoditybalancevalue/ returns data points.
https://fdw.fews.net/api/commoditybalancefacts/ returns data points plus calculated facts (e.g., percent change from one year, five year average).
https://fdw.fews.net/api/commoditybalancedataset/ returns data sets.
There is one domain-specific filter, Document Type, which has two options: Commodity Balance Sheet Estimate and Final Commodity Balance Sheet.
If the uploaded unit of measure differs from the default, the data will be returned in both uploaded and default units to allow easier comparison between different data sets.