API

LEX offers a comprehensive REST API to access data based on user permissions. This API provides more flexibility than the LEX user interface.

The LEX REST API supports extensive functions. Interactive API documentation is available.

Authentication

A small amount of information in the Livelihoods Explorer is not available publicly. This includes the list of specific community names and links to download the original BSS files. In order to access this information, users must be authenticated by logging in to the Livelihoods Explorer. After logging in, your browser will send a session cookie automatically to authenticate requests to the API. 

If you do not authenticate or lack permission to access the data:

• You may receive the error “no data found” when you query data that has restricted permissions.

• Not all expected data may be included in the response.

API link structure

Each URL consists of up to 5 parts: the base URL, the endpoint, output format, filters, and fields.

Base URL

The base URL for the Livelihoods Explorer API is https://livelihoods.fews.net/api/.

Endpoints

This API includes a number of endpoints.

The most useful endpoints for individuals doing data analysis are:

The most useful endpoints for individuals involved in gathering and submitting BSS data are:

Additional endpoints include:

Output format

All endpoints support a standard range of extract formats, which can be accessed using an extension on the URL (for example, https://livelihoods.fews.net/api/livelihoodactivitysummary.html) or a query parameter (for example, https://livelihoods.fews.net/api/livelihoodactivitysummary/&format=json).

The standard values for the format parameter include:

• html : a plain HTML table

• json : a JavaScript Object Notation text string

• csv : a UTF-8 comma-separated values file with a header row and a UTF-8 byte order mark (BOM) to enable Microsoft Excel and other tools to recognize the file correctly

• xml : an extensible markup language text string. XML is the recommended format for importing data into Microsoft Excel.

The livelihoodzonebaseline endpoint also supports spatial extracts using the geojson extract format.

Filters and pagination

Many of the time series data domains contain a large amount of data, such that attempting to extract all of it in a single request may fail due to browser timeouts. Best practice is to filter the request to include only the data that is required, or to use pagination to limit the size of each response.

Filters

Options for filters are unique to the end point. Some of the most common and/or useful filter options are described below. To view a full list of options for your endpoint, view our comprehensive, interactive API documentation.

• Geography

  • country_code : The ISO 3166-1 alpha-2 two letter code for a country. Options can be found using https://livelihoods.fews.net/api/country/.
    Example: &country_code=KE

  • country : Similar to the country_code filter above, but uses the name of the country rather than the ISO code. This is easier to use, but may be slower, especially for large extracts. Example: ?country=Kenya

  • livelihood_zone: A Livelihood Zone code such as ML12. Options can be found using https://livelihoods.fews.net/api/livelihoodzone/.

• Livelihoods and Baselines

  • main_livelihood_category: The dominant pattern of livelihoods for a Livelihood Zone, such as pastoral or urban. Also called livelihood zone system or production system. Options can be found using https://livelihoods.fews.net/api/livelihoodcategory/.

  • wealth_group_category: A Wealth Group Category such as Poor (P) or Better off (B/O). Options can be found using https://livelihoods.fews.net/api/wealthgroupcategory/.

  • wealth_characteristic: An attribute of a Wealth Group such as the number of school-age children. Options can be found using https://livelihoods.fews.net/api/wealthcharacteristic/.

  • strategy_type: A type of livelihood strategy, such as crop production. Options include MilkProduction, ButterProduction, MeatProduction, LivestockSale, CropProduction, FoodPurchase, PaymentInKind, ReliefGiftOther, Hunting, Fishing, WildFoodGathering, OtherCashIncome, OtherPurchase.

  • scenario: A Livelihood Activity contains the outputs of a Livelihood Strategy employed by one of the following:

    • A Wealth Group in a Community in the reference year

    • A Wealth Group representing the Baseline as a whole in the reference year (the baseline scenario)

    • A Wealth Group representing the Baseline as a whole in response to a shock (the response scenario)

  • as_of_date: Using as_of_date equal to today will filter out Baselines that are no longer valid. Dates should be in the format YYYY-MM-DD. Example: as_of_date=2026-06-12.

• Products

  • cpc : CPC is the UN’s Central Product Classification. CPC is a hierarchy, so specifying L02122AF will return only those matching records, whereas filtering for L02122 would return prices for both L02122AA and L02122AF. Options can be found using https://livelihoods.fews.net/api/classifiedproduct/
    Example: ?cpc=L02122

  • product : A given product name or description. This is easier to use, but may be slower and less accurate than filtering using the cpc .
    Example: ?product=maize

• Seasonal calendars

  • season_type: The classification of a specific time of year based on weather patterns, temperature, and other factors. Options include harvest, lean, wet, dry, mild, spring, summer, fall, winter, and monsoon.

  • activity_category: Types of seasonal activities. Options include climatology, stress_periods, crop, livestock, fishing, other_income, and other.

  • seasonal_activity_type: A specific activity type such as weeding, harvesting, or births. Options can be found using https://livelihoods.fews.net/api/seasonalactivitytype/.

Pagination

When using JSON-formatted responses, the data can be paginated by passing page_size and offset parameters as part of the request.

For example a request for https://livelihoodsdev.fews.net/api/country.json?page_size=10&offset=0 will return the following response:

{
"count": 251,
"next": "https://livelihoodsdev.fews.net/api/country.json?offset=0&page=2&page_size=10",
"previous": null,
"results": [
    <snip>
]
}

Fields

By default the API responses will contain a large number of fields. For some domains they may include various additional statistics such as the value one year ago or the five-year average. It is possible to control which fields are returned by the API using the fields parameter.

A reduced set of the commonly used fields can be selected using &fields=simple.

Alternatively, specific fields can be specified in a comma-separated list such as &fields=dataseries,start_date,period_date,value,two_year_average .

Ordering

Results can be ordered based on select fields. To order by a specific field, use &ordering=[field] such as &ordering=livelihood_zone. Default is to order ascending. To order descending, add a - before the field name such as &ordering=-livelihood_zone.

Additional support

The LEX REST API has a wide range of functionality. Comprehensive, interactive API documentation is available.

If your use case is not covered by our documentation, please contact Help Desk Support.