Commodity Balance Data

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: 

1. Country

2. Item (Indicator)

3. Crop (Commodity) 

4. Data Source Document

5. Values (periods as one column or multiple periods/columns)

It is best practice to use the same indicator and crop names as used in previous periods if possible.

Currently, the FDW will recognize the following column headers: datasourcedocument , data_source_organization , data_source_document , schedule , data_usage_policy , country , geographic_group , fewsnet_region , start , end , id , created , modified , specialization_type , name , description , metadata , geographic_unit , indicator , is_calculated , _search , _country , datausagepolicy , original_data_source , product , unit , dataseries_ptr.

Important: If you regularly receive a document from a non-FEWS NET source that contains alternate column headings, do not edit the column headings every time. Instead, submit a help desk ticket so the Hub can add the headings as aliases to the system.

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

Commodity balance sheet data must be uploaded twice: under Commodity Balances and Commodity Balance Values.

1. Go to Dataseries Management > Commodity Balances > Commodity Balances.

2. Click Import Commodity Balances.

3. Click Choose File and select your spreadsheet to load the file.

4. Click Submit and the file will be in draft status. 

5. Go to Dataseries Management > Data Points > Commodity Balance Values.

6. Click Import Commodity Balance Values.

7. Click Choose File and select the same spreadsheet to load the file.

8. 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/commoditybalancedataset/ returns data sets.

• 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).

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.