Livelihoods Explorer
English Spanish French
English Spanish French

LivelihoodProductCategory and ThresholdComponent

The Survival and Livelihoods Protection Thresholds for a Baseline are built from the allocation of the Wealth Groups' food and non-food purchases to the four baskets (main staple, survival other food, survival non-food, and livelihoods protection).

Learn more about Thresholds and baskets.

The API exposes Threshold and basket information through two related, but distinct, endpoints that are based on Livelihood Product Categories.

A Livelihood Product Category is a record of how a specific group of people buys and uses a particular item to meet their basic needs.

Instead of just looking at total spending or consumption, it tracks:

  • The product or service: What is being purchased (such as maize grain, medicine, school fees, or farming tools).

  • The baseline activity: How much money is spent on it or how much food energy (calories) it provides as a percent of 2100 kcals per person per day.

  • The basket: Where that purchase fits into a household's needs—whether it goes toward basic staple food, other essential survival foods, non-food survival needs (like cooking fuel or soap), or protecting their long-term livelihood (like livestock feed or crop fertilizer).

  • The allocation: How much of reference year annual spending on that item is included in the basket. For example, OtherPurchase of kerosene may be allocated as 75% in the survival non-food purchases basket since only 75% of the amount of kerosene used in the reference year would be essential for survival. Because LEX only stores one category per product, the remaining 25% would implicitly be part of an “other” basket of discretionary spending that is not associated with either the Survival or Livelihood Protection Thresholds and will not be returned in these endpoints.

The two endpoints that use Livelihood Product Categories are livelihoodproductcategory and thresholdcomponent.


livelihoodproductcategory

thresholdcomponent

Summary

A concise list of items included in baskets. Items that are identical across Wealth Groups in a Baseline are not repeated. This is equivalent to the data recorded in the Baseline.

A complete view of the items that make up the Thresholds for each Wealth Group.

Use

Review (and correct) the allocations that were entered for the Baseline

Explain or chart the Threshold for each Wealth Group

Returns one row of results per

Returns one row of results per Livelihood Product Category. Items in baskets 1-3 are returned for the Poor Wealth Group only. Items in basket 4 are returned for each Wealth Group that has its own allocation.

Returns one row of results per Livelihood Product Category for each Wealth Group whose Threshold it contributes to, including Wealth Groups that don't have any Livelihood Product Categories of their own. is_inherited and source_wealth_group_category show which Wealth Group each row came from.

Editable

Yes

No, read only

Example

This URL will produce a list of Livelihood Product Categories for Baseline 1233.

https://livelihoods.fews.net/api/livelihoodproductcategory.json?livelihood_zone_baseline=1233

This URL will produce a complete list of basket contents for all Wealth Groups in Baseline 1223.

https://livelihoods.fews.net/api/thresholdcomponent.json?livelihood_zone_baseline=1233

Livelihood Product Category

The livelihoodproductcategory endpoint returns the Livelihood Product Categories that are stored for the Baseline.

Livelihood Product Categories are only recorded where the BSS contains an allocation:

  • Baskets 1, 2 and 3 are only recorded for the Poor Wealth Group.

  • Basket 4 is only recorded for the Wealth Groups that have their own Livelihoods Protection allocations.

  • A Wealth Group may not have any Livelihood Product Categories at all.

Each row contains the value entered in the BSS, plus the amounts from the Baseline Livelihood Activity and the calculated contribution to the Basket.

Threshold Component

The thresholdcomponent endpoint applies inheritance rules to the Livelihood Product Categories to produce the complete list of items in the Threshold for every Wealth Group.

Composition of the Livelihoods Protection Basket

The Livelihoods Protection Threshold for each Wealth Group is built from the four Baskets defined by the Livelihood Product Categories for the Baseline.

Baskets 1, 2 and 3 make up the Survival Threshold and are defined for the Poor Wealth Group. Every Wealth Group inherits these baskets from the Poor Wealth Group.

Basket 4 can be defined separately for each Wealth Group. Every Wealth Group gets its own basket 4 Livelihood Product Categories. If a Wealth Group does not have its own allocation for a Livelihood Strategy in basket 4, it will inherit the associated Livelihood Product Category from the Poor Wealth Group. Therefore, a single Livelihood Product Category can appear as a component of the Threshold for several Wealth Groups.

The thresholdcomponent endpoint returns each component, and its basket_percentage_kcals is the contribution of the component as a percentage of 2100 kcals/person/day. The contributions to each basket are calculated as follows:

  1. Main Staple - the remainder of the 100% kcals requirement after Basket 2 (Other Food Survival). Note that the basket_percentage_kcals for the Main Staple is not derived from either the percentage_kcals from the Crop Production for that crop or the percentage_kcals from Food Purchase of that crop. The Thresholds assume that households will purchase the main staple crop to reach 100% of required kcals after consuming the kcals from the Survival Other Food basket.

  2. Other food survival - percentage_kcals × percentage_allocation_to_basket

  3. Non-food survival - expenditure × percentage_allocation_to_basket, converted to kcals using the annual_kcals_cost

  4. Livelihoods Protection - expenditure × percentage_allocation_to_basket, converted to kcals. Following the calculations used in the Baselines, the percentage kcals from the product is removed.

The endpoint returns one row for each Wealth Group that each Livelihood Product Category contributes to, so a single API call returns all the components for every Wealth Group in the Baseline.

Filters

Useful filters for these endpoints include the following:

Filter

Accepted values

livelihood_zone

Use a Livelihood Zone code such as ML12.

livelihood_zone_baseline

Use a Baseline code such as 1233.

product

Use a name, alias, product code such as R01122.

basket

1 (Main staple)

2 (Other food survival)

3 (Non-food survival)

4 (Livelihoods protection)

basket=1&basket=2&basket=3 Returns just the components of the Survival Threshold

strategy_type

FoodPurchase will return food items from baskets 1, 2, and 4.

OtherPurchase will return non-food items from baskets 3 and 4.

Example

Pull a list of Livelihood Zone Baselines in which maize/corn grain is the main staple (basket 1):

https://livelihoods.fews.net/api/livelihoodproductcategory.html?product=R01122&basket=1

Fields

You select the fields you want to view by using the fields parameter in the usual way.

Important fields for these endpoints include:

Field name

Definition

source_wealth_group, source_wealth_group_category, source_wealth_group_category_name, and source_wealth_group_category_short_name

Identifies the source of the allocation for the Threshold Component. If a component has been inherited (is_inherited = True) then this field will be equal to Poor. If a component has not been inherited then this will be equal to the Wealth Group represented by the row.

These fields are only returned in the thresholdcomponent endpoint.

is_inherited

Returns True if the Threshold Component has been inherited from the Poor Wealth Group.

This field is only returned in the thresholdcomponent endpoint.

percentage_allocation_to_
basket

The proportion of the activity allocated to the Basket, as entered in the BSS. For each basket 4 Product, this endpoint shows which Wealth Groups have their own allocation. A blank cell means that the Wealth Group doesn't have its own Livelihood Product Category for that Product, and so the Threshold for that Wealth Group will use the allocation from the Poor Wealth Group instead.

activity_percentage_kcals

The percentage of 2100 kcals per person per day for the Baseline Livelihood Activity

activity_expenditure

The total expenditure for the Baseline Livelihood Activity in local currency

allocated_percentage_kcals

The parts of the totals that are allocated to the Basket e.g., percentage_allocation_to_basket × activity_percentage_kcals

allocated_expenditure

The parts of the totals that are allocated to the Basket e.g., percentage_allocation_to_basket × activity_expenditure

allocated_expenditure_as_
percentage_kcals

The allocated expenditure converted to kcals using the annual_kcals_cost

basket_percentage_kcals

The contribution to the Threshold, as a percentage of 2100 kcals/person/day. This is equal to the following for each basket:

  • Basket 1: 2100 - the sum of allocated_percentage_kcals for all Livelihood Activities in basket 2.

  • Basket 2: allocated_percentage_kcals

  • Basket 3: allocated_expenditure_as_percentage_kcals

  • Basket 4: allocated_expenditure_as_percentage_kcals - allocated_percentage_kcals

Other fields include:

  • id (The livelihood_product_category field in each Threshold Component is the id of the Livelihood Product Category.)

  • livelihood_product_category

  • source_organization

  • source_organization_name

  • baseline_livelihood_activity

  • livelihood_zone

  • livelihood_zone_baseline

  • livelihood_zone_baseline_label

  • livelihood_zone_name

  • livelihood_zone_country

  • livelihood_zone_country_name

  • wealth_group

  • wealth_group_category

  • wealth_group_category_name

  • wealth_group_category_short_name

  • basline_livelihood_activity

  • baseline_strategy

  • strategy_type

  • basket

  • basket_name

  • product

  • product_common_name

  • product_description

  • season

  • season_name

  • additional_identifier

  • livelihood_strategy