API Reference
data_bridges_knots.client.DataBridgesShapes
DataBridgesShapes is a class that provides an interface to interact with the Data Bridges API.
This class includes methods for fetching various types of data such as market prices, exchange rates, food security data, commodities, and more. The class can be initialized with either a YAML configuration file or a configuration dictionary, and supports multiple environments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
str | dict
|
Either: - Path to YAML configuration file (str), or - Configuration dictionary (dict) with required keys: KEY, SECRET, VERSION, SCOPES, and optionally DATABRIDGES_API_KEY |
required |
env
|
str
|
Environment to use ('prod' or 'dev'). Defaults to "prod" |
'prod'
|
Examples:
>>> # Initialize with YAML file (traditional method)
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> df_prices = client.get_prices("KEN", "2025-09-01")
>>> # Initialize with dictionary (new method)
>>> config = {
... 'KEY': 'your-api-key',
... 'SECRET': 'your-api-secret',
... 'VERSION': '5.0.0',
... 'SCOPES': ['vamdatabridges_household-fulldata_get'],
... 'DATABRIDGES_API_KEY': 'optional-databridges-key'
... }
>>> client = DataBridgesShapes(config)
>>> exchange_rates = client.get_exchange_rates("ETH")
>>> # Initialize from environment variables
>>> from data_bridges_knots.client import config_from_env
>>> config = config_from_env()
>>> client = DataBridgesShapes(config)
get_aims_analysis_rounds(adm0_code)
Download all analysis rounds for AIMS (Asset Impact Monitoring System) data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adm0_code
|
int
|
The country adm0Code. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bytes |
The downloaded data as bytes. |
get_aims_polygon_files(adm0_code)
Download polygon files for Landscape Impact Assessment (LIA) assets.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
adm0_code
|
int
|
The country adm0Code. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bytes |
The downloaded polygon files as bytes. |
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 = DataBridgesShapes("data_bridges_api_config.yaml")
>>> choices = client.get_choice_list(123)
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 = DataBridgesShapes("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_code
|
str
|
The code to identify the country. It can be an ISO-3166 Alpha 3 code or the VAM internal admin0code. |
required |
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 = DataBridgesShapes("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 = DataBridgesShapes("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 |
|---|---|
|
pandas.DataFrame: A DataFrame containing the retrieved commodity units data. |
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 = DataBridgesShapes("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 |
|---|---|
|
pandas.DataFrame: A DataFrame containing the retrieved currency data. |
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 ''. |
''
|
iso3
|
str
|
The code to identify the country. Must be a ISO-3166 Alpha 3 code. Defaults to ''. |
required |
format
|
str
|
Output format: 'json' or 'csv'. Defaults to 'json'. |
'json'
|
Returns:
| Type | Description |
|---|---|
|
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 = DataBridgesShapes("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_food_security_list(iso3=None, year=None, page=1)
Retrieves food security data from IPC and equivalent data sources
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iso3
|
str
|
The country ISO3 code |
None
|
year
|
int
|
The year to retrieve data for |
None
|
page
|
int
|
Page number for paged results. Defaults to 1 |
1
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing food security data with relevant indicators and metrics for the specified country and year |
Examples:
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get food security data for Ethiopia in 2023
>>> eth_food_security = client.get_food_security_list("ETH", 2025)
>>> # Get all food security data
>>> all_food_security = client.get_food_security_list()
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error calling the Food Security API |
get_gorp(data_type, page=None)
Retrieves data from the Global Operational Response Plan (GORP) API.
The GORP API provides access to WFP's operational response planning data at different geographical levels.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data_type
|
str
|
The type of GORP 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. Required for 'latest' and 'list' data types. Defaults to None. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing data from the Global Operational Response Plan (GORP) |
Examples:
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get latest country-level data
>>> country_data = client.get_gorp("country_latest")
>>> # Get global summary
>>> global_data = client.get_gorp("global_latest")
>>> # Get regional breakdown
>>> regional_data = client.get_gorp("regional_latest")
Raises:
| Type | Description |
|---|---|
ValueError
|
If data_type is not one of the allowed values |
ApiException
|
If there's an error accessing the GORP 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 = DataBridgesShapes("data_bridges_api_config.yaml")
>>> questionnaire = client.get_household_questionnaire(2075)
get_household_survey(survey_id, access_type, page_size=600)
Retrieves 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
|
The type of access to use. Must be one of: - 'draft': Draft internal base data (requires API key) - 'full': Complete survey data (requires API key). Data is returned as inserted by the country office and it might contain PII and unstandardized fields.
|
required |
page_size
|
int
|
Number of items per page. Defaults to 600 |
600
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing survey data with columns specific to the access type and survey structure |
Examples:
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get full, unmapped survey data
>>> full_data = client.get_household_survey(3094, "full")
>>> # Get standard data for official use (no PII)
>>> official_data = client.get_household_survey(3094, "official")
Raises:
| Type | Description |
|---|---|
KeyError
|
If access_type is not one of the allowed values |
ApiException
|
If there's an error accessing the API |
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 = DataBridgesShapes("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_xslform_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 = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get form definition
>>> form_def = client.get_household_xslform_definition(2067)
>>> # Access form fields
>>> fields = form_def['fields'].iloc[0]
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error accessing the 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 = DataBridgesShapes("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_markets_list(country_iso3=None, page=1)
Retrieves a complete list of markets in a country.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
country_code
|
str
|
The ISO3 code to identify the country. Defaults to None. |
required |
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 = DataBridgesShapes("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_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_base_data(survey_id=None, page=1, page_size=20)
Get data that includes the core Market Functionality Index (MFI) fields only by Survey ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
survey_id
|
int
|
Unique identifier for the collected data |
None
|
page
|
int
|
Page number for paged results |
1
|
page_size
|
int
|
Number of items per page |
20
|
Examples:
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get MFI base data for a specific survey
>>> base_data = client.get_mfi_surveys_base_data(survey_id=123)
Returns:
| Type | Description |
|---|---|
|
pandas.DataFrame: DataFrame containing MFI base survey data |
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_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 = DataBridgesShapes("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 |
|---|---|
|
pandas.DataFrame: DataFrame containing XLS Forms data |
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 = DataBridgesShapes("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, survey_date=None, page_size=1000)
Fetches market price data for a given country and survey date.
Args: country_iso3 (str): The ISO 3-letter country code survey_date (str, optional): The survey date in ISO format (e.g. '2022-01-01'). If None, fetches data from the last 12 months. Defaults to None. page_size (int, optional): Number of items per page. Defaults to 1000
Returns:
| Type | Description |
|---|---|
DataFrame
|
pd.DataFrame: DataFrame containing market price data with columns: - date: Date of price recording - price: Price value - commodity_id: ID of the commodity - market_id: ID of the market And other relevant price information |
Examples:
>>> client = DataBridgesShapes("data_bridges_api_config.yaml")
>>> # Get prices for last 12 months
>>> df_prices = client.get_prices("KEN")
>>> # Get prices from specific date
>>> df_date_prices = client.get_prices("KEN", "2025-09-01")
Raises:
| Type | Description |
|---|---|
ApiException
|
If there's an error calling the Market price API |
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 = DataBridgesShapes("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 |
|---|---|
|
pandas.DataFrame: A DataFrame containing the retrieved exchange rate data. |