API Reference
data_bridges_knots.client.DataBridgesKnots
Bases: CommodityApi, CurrencyApi, EconomicDataApi, GlobalOutlookApi, HouseholdApi, HungerHotspotApi, IncubationApi, IpcchApi, MarketPricesApi, MarketsApi, MfiSurveysApi, RpmeApi
Interface to the Data Bridges API.
Provides methods for fetching market prices, exchange rates, food security data, commodities, and more. Can be initialized from a YAML file, a dictionary, or environment variables.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_path
|
str | dict
|
Either: - Path to a YAML configuration file (str), or - Configuration dictionary (e.g. .env) with required keys: WFP_API_CLIENT_ID, WFP_API_CLIENT_SECRET, and optionally DATABRIDGES_API_KEY |
required |
env
|
str
|
Environment to use ('prod' or 'dev'). Defaults to "prod". |
'prod'
|
api_version
|
str
|
Data Bridges API version to use. Defaults to "v2" (current version) |
'v2'
|
Examples:
>>> # Initialize with YAML file
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> df_prices = client.get_prices("KEN", "2025-09-01")
>>> # Initialize with dictionary
>>> config = {
... 'WFP_API_CLIENT_ID': 'your-client-id',
... 'WFP_API_CLIENT_SECRET': 'your-client-secret',
... 'DATABRIDGES_API_KEY': 'optional-databridges-key'
... }
>>> client = DataBridgesKnots(config)
>>> # Initialize from environment variables
>>> from data_bridges_knots.client import config_from_env
>>> client = DataBridgesKnots(config_from_env())
get_mfi_surveys_base_data(survey_id=None, page=1, page_size=20)
Retrieve Market Functionality Index (MFI) base survey data.
Returns survey data containing only the core MFI fields for a given survey ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
survey_id
|
int
|
Unique identifier of the survey. If not provided, results may include multiple surveys depending on API behavior. |
None
|
page
|
int
|
Page number for paginated results. Defaults to |
1
|
page_size
|
int
|
Number of records per page. Defaults to |
20
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: DataFrame containing MFI base survey data. |
Raises:
| Type | Description |
|---|---|
ApiException
|
If the API request fails. |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get MFI base data for a specific survey
>>> df = client.get_mfi_surveys_base_data(survey_id=123)
get_mfi_surveys_full_data(survey_id=None, page=1, page_size=20)
Get a full dataset that includes all the fields included in the survey in addition to the core Market Functionality Index (MFI) fields by Survey ID.
get_mfi_surveys(adm0_code=0, page=1, start_date=None, end_date=None)
Retrieve Survey IDs, their corresponding XLS Form IDs, and Base XLS Form of all MFI surveys conducted in a country.
get_mfi_surveys_processed_data(survey_id=None, page=1, page_size=20, format='json', start_date=None, end_date=None, adm0_codes=None, market_id=None, survey_type=None)
Get MFI processed data in long format.
get_mfi_xls_forms_detailed(adm0_code=0, page=1, start_date=None, end_date=None)
Get a complete list of XLS Forms uploaded on the MFI Data Bridge in a given period of data collection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adm0_code
|
int
|
Code for the country. Defaults to 0. |
0
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
start_date
|
str
|
Starting date for data collection range (YYYY-MM-DD format) |
None
|
end_date
|
str
|
Ending date for data collection range (YYYY-MM-DD format) |
None
|
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get detailed XLS forms for country code 231
>>> detailed_forms = client.get_mfi_xls_forms_detailed(adm0_code=231)
>>> # Get forms within a date range
>>> forms_in_range = client.get_mfi_xls_forms_detailed(
... adm0_code=231,
... start_date="2023-01-01",
... end_date="2023-12-31"
... )
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: DataFrame containing XLS Forms data |
get_market_geojson_list(country_iso3=None)
Returns a list of geo-referenced markets in a specific country.
get_markets_list(country_iso3=None, page=1)
Retrieves a complete list of markets in a country.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The ISO3 code to identify the country. Defaults to None. |
None
|
page
|
int
|
Page number for paginated results. Defaults to 1. |
1
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing market information with columns: - market_id: Unique identifier for the market - market_name: Name of the market - adm0_code: Country administrative code - latitude: Market location latitude - longitude: Market location longitude And other market-related fields |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get markets for Afghanistan
>>> afg_markets = client.get_markets_list("AFG")
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the Markets API |
get_markets_as_csv(country_iso3=None, local_names=False)
Retrieves a complete list of markets in a country in CSV format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
Country administrative code. Defaults to None. |
None
|
local_names
|
bool
|
If True, market and region names will be localized if available. Defaults to False. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
CSV formatted string containing market data |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get markets CSV for Afghanistan
>>> markets_csv = client.get_markets_as_csv("AFG")
>>> # Get localized market names
>>> local_markets = client.get_markets_as_csv("AFG", local_names=True)
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the Markets API |
get_nearby_markets(country_iso3=None, lat=None, lng=None)
Finds markets near a given location within a 15km distance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
Country administrative code. Defaults to None. |
None
|
lat
|
float
|
Latitude of the search point. Defaults to None. |
None
|
lng
|
float
|
Longitude of the search point. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing nearby markets with columns: - market_id: Unique identifier for the market - market_name: Name of the market - distance: Distance from search point in kilometers - latitude: Market location latitude - longitude: Market location longitude And other market-related fields |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Find markets near coordinates in Afghanistan
>>> nearby = client.get_nearby_markets("AFG", 34.515, 69.208)
>>> # Sort markets by distance
>>> closest = nearby.sort_values('distance').iloc[0]
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the Markets API |
get_prices(country_iso3, start_date=None, end_date=None, page_size=1000, market_id=0, commodity_id=0, currency_id=0, price_flag='', latest_value_only=False)
Fetches market price data for a given country within a specified date range.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The ISO 3-letter country code |
required |
start_date
|
str
|
Start date in ISO format (e.g., '2022-01-01'). If None, defaults to today's date. |
None
|
end_date
|
str
|
End date in ISO format (e.g., '2022-01-01'). If None, defaults to today's date. |
None
|
page_size
|
int
|
Number of items per page. Defaults to 1000. |
1000
|
market_id
|
int
|
Unique ID of a Market. Defaults to 0. |
0
|
commodity_id
|
int
|
The exact ID of a Commodity. Defaults to 0. |
0
|
currency_id
|
int
|
The exact ID of a currency. Defaults to 0. |
0
|
price_flag
|
str
|
Type of price data: [actual|aggregate|estimated|forecasted]. Defaults to ''. |
''
|
latest_value_only
|
bool
|
Whether to return only latest values. Defaults to False. |
False
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing market price data |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Basic usage with dates
>>> df_prices = client.get_prices("KEN", start_date="2025-01-01", end_date="2025-12-31")
>>> # Using additional filters
>>> df_prices = client.get_prices(
... "KEN",
... start_date="2025-01-01",
... market_id=123,
... commodity_id=456,
... price_flag="actual"
... )
get_household_survey(survey_id, access_type, page_size=600, **kwargs)
Retrieve household survey data using the specified access type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
survey_id
|
int
|
The ID of the survey to retrieve. |
required |
access_type
|
str
|
Type of access. Must be one of:
- |
required |
page_size
|
int
|
Number of items per page. Defaults to |
600
|
**kwargs
|
bool
|
optional parameters (only used when
|
{}
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: Survey data as a DataFrame. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If |
ApiException
|
If the API request fails. |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Full data with mapping
>>> df = client.get_household_survey(3094, "full", apply_mapping=True)
>>> # Official standardized data
>>> df = client.get_household_survey(3094, "official")
get_household_surveys_list(country_iso3=None, page=1, start_date=None, end_date=None, survey_id=None)
Retrieves a list of household surveys for a country with their metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
ISO3 Country code |
None
|
page
|
int
|
Page number for paginated results. Defaults to 1 |
1
|
start_date
|
str
|
Start date filter in ISO format (YYYY-MM-DD) |
None
|
end_date
|
str
|
End date filter in ISO format (YYYY-MM-DD) |
None
|
survey_id
|
int
|
Specific survey ID to retrieve |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing survey metadata with columns: - survey_id: Unique identifier for the survey - xls_form_id: ID of the questionnaire form used - title: Survey title - country: Country name - start_date: Survey start date - end_date: Survey end date And other metadata fields |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get all surveys for a country
>>> surveys = client.get_household_surveys_list(country_iso3="COG")
>>> # Get surveys within date range
>>> surveys = client.get_household_surveys_list(
... country_iso3="COG",
... start_date="2024-01-01",
... end_date="2024-12-31"
... )
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the API |
get_household_xlsform_definition(xls_form_id)
Retrieves the complete XLS Form definition for a questionnaire.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xls_form_id
|
int
|
The ID of the questionnaire form to retrieve |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing the form definition with columns: - fields: List of field definitions - choices: Available choices for select questions - settings: Form settings And other form structure information |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get form definition
>>> form_def = client.get_household_xlsform_definition(2067)
>>> # Access form fields
>>> fields = form_def['fields'].iloc[0]
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the API |
get_household_questionnaire(xls_form_id)
Extracts the questionnaire structure from an XLS Form definition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xls_form_id
|
int
|
The ID of the questionnaire form to process |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing the questionnaire structure with one row per field in the form |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> questionnaire = client.get_household_questionnaire(2075)
get_choice_list(xls_form_id)
Extracts choice lists from a questionnaire form definition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
xls_form_id
|
int
|
The ID of the questionnaire form to process |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing choice lists with columns: - name: Name of the choice list - value: Choice value/code - label: Human-readable choice label |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> choices = client.get_choice_list(123)
get_global_outlook(data_type, page=None)
Retrieves data from the Global Outlook API.
The Global Outlook API provides access to WFP’s forward-looking analysis and aggregated insights at different geographical levels, including country, regional, and global summaries.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data_type
|
str
|
The type of Global Outlook data to retrieve. Must be one of: - 'country_latest': Latest data at country level - 'global_latest': Latest global aggregated data - 'regional_latest': Latest data aggregated by region |
required |
page
|
int
|
Page number for paginated results. Currently not used for latest endpoints. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing Global Outlook data for the selected scope. |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get latest country-level outlook
>>> country_data = client.get_global_outlook("country_latest")
>>> # Get global outlook summary
>>> global_data = client.get_global_outlook("global_latest")
>>> # Get regional outlook data
>>> regional_data = client.get_global_outlook("regional_latest")
Raises:
| Type | Description |
|---|---|
ValueError
|
If data_type is not one of the allowed values |
ApiException
|
If there is an error accessing the Global Outlook API |
get_economic_indicator_list(page=1, indicator_name='', country_iso3='', format='json')
Returns the lists of indicators for which Vulnerability Analysis and Mapping - Economic and Market Analysis Unit has redistribution licensing from Trading Economics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
indicator_name
|
str
|
Unique indicator name. Defaults to ''. |
''
|
country_iso3
|
str
|
The code to identify the country. Must be a ISO-3166 Alpha 3 code. Defaults to ''. |
''
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved economic indicator data. |
get_exchange_rates(country_iso3, page_size=1000)
Retrieves exchange rates for a given country from the Data Bridges API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The ISO3 country code |
required |
page_size
|
int
|
Number of items per page. Defaults to 1000 |
1000
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing exchange rate data with columns: - date: Date of exchange rate - rate: Exchange rate value - currency: Currency code And other relevant exchange rate information |
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get exchange rates for Ethiopia
>>> rates_df = client.get_exchange_rates("ETH")
>>> # Check latest exchange rate
>>> latest_rate = rates_df.sort_values('date').iloc[-1]
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error calling the Exchange rates API |
get_currency_list(country_iso3=None, currency_name=None, currency_id=0, page=1, format='json')
Returns the list of currencies available in the internal VAM database, with Currency 3-letter code, matching with ISO 4217.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The code to identify the country. It can be an ISO-3166 Alpha 3 code or the VAM internal admin0code. |
None
|
currency_name
|
str
|
Currency 3-letter code, matching with ISO 4217. |
None
|
currency_id
|
int
|
Unique code to identify the currency in internal VAM currencies. Defaults to 0. |
0
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get currencies for Tanzania
>>> currencies_df = client.get_currency_list(country_iso3="TZA")
>>> # Get currency with name "ETB"
>>> etb_df = client.get_currency_list(currency_name="ETB")
>>> # Get currency with specific ID
>>> specific_currency_df = client.get_currency_list(currency_id=1)
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved currency data. |
get_usd_indirect_quotation(country_iso3='', currency_name='', page=1, format='json')
Returns the value of the Exchange rates from Trading Economics, for official rates, and DataViz for unofficial rates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The code to identify the country. Must be a ISO-3166 Alpha 3 code. Defaults to ''. |
''
|
currency_name
|
str
|
The ISO3 code for the currency, based on ISO4217. Defaults to ''. |
''
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get USD indirect quotation for Ethiopia
>>> usd_df = client.get_usd_indirect_quotation(country_iso3="ETH")
>>> # Get USD indirect quotation for currency "ETB"
>>> etb_usd_df = client.get_usd_indirect_quotation(currency_name="ETB")
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved exchange rate data. |
get_commodities_list(country_iso3=None, commodity_name=None, commodity_id=0, page=1, format='json')
Retrieves the detailed list of commodities available in the DataBridges platform.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The code to identify the country. It can be an ISO-3166 Alpha 3 code or the VAM internal admin0code. |
None
|
commodity_name
|
str
|
The name, even partial and case insensitive, of a commodity. |
None
|
commodity_id
|
int
|
The exact ID of a commodity. Defaults to 0. |
0
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get full list of commmodities
>>> commodities_list = client.get_commodities_list()
>>> # Get commodities for Tanzania
>>> commodities_df = client.get_commodities_list(country_iso3="TZA")
>>> # Get commodity with name containing "Maize"
>>> maize_df = client.get_commodities_list(commodity_name="Maize")
>>> # Get commodity with specific ID
>>> specific_commodity_df = client.get_commodities_list(commodity_id=123)
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved commodity data. |
get_commodity_units_conversion_list(country_iso3=None, commodity_id=0, from_unit_id=0, to_unit_id=0, page=1, format='json')
Retrieves conversion factors to Kilogram or Litres for each convertible unit of measure.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The code to identify the country. It can be an ISO-3166 Alpha 3 code or the VAM internal admin0code. |
None
|
commodity_id
|
int
|
The exact ID of a Commodity, as found in /Commodities/List. Defaults to 0. |
0
|
from_unit_id
|
int
|
The exact ID of the original unit of measure of the price of a commodity. Defaults to 0. |
0
|
to_unit_id
|
int
|
The exact ID of the converted unit of measure of the price of a commodity. Defaults to 0. |
0
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Examples:
client = DataBridgesKnots("data_bridges_api_config.yaml")
Get full list of commodity units conversions
full_list = client.get_commodity_units_conversion_list()
Get conversion factors for Tanzania
conversion_factors_df = client.get_commodity_units_conversion_list(country_iso3="TZA")
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved conversion factors. |
get_commodity_units_list(country_iso3=None, commodity_unit_name=None, commodity_unit_id=0, page=1, format='json')
Retrieves the detailed list of the unit of measure available in DataBridges platform.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_iso3
|
str
|
The code to identify the country. It can be an ISO-3166 Alpha 3 code or the VAM internal admin0code. |
None
|
commodity_unit_name
|
str
|
The name, even partial and case insensitive, of a commodity unit. |
None
|
commodity_unit_id
|
int
|
The exact ID of a commodity unit. Defaults to 0. |
0
|
page
|
int
|
Page number for paged results. Defaults to 1. |
1
|
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Examples:
>>> client = DataBridgesKnots("data_bridges_api_config.yaml")
>>> # Get commodity units for Tanzania
>>> units_df = client.get_commodity_units_list(country_iso3="TZA")
>>> # Get commodity unit with name containing "Kg"
>>> kg_unit_df = client.get_commodity_units_list(commodity_unit_name="Kg")
>>> # Get commodity unit with specific ID
>>> specific_unit_df = client.get_commodity_units_list(commodity_unit_id=5)
Returns:
| Type | Description |
|---|---|
DataFrame
|
pandas.DataFrame: A DataFrame containing the retrieved commodity units data. |