From 0d307298be84571037b3a66fd290a45333505ed7 Mon Sep 17 00:00:00 2001 From: Alessandra Gherardelli Date: Fri, 29 Nov 2024 16:07:40 +0100 Subject: [PATCH] feature: add SurveyApi endpoints --- ROADMAP.md | 22 +++---- data_bridges_knots/client.py | 111 ++++++++++++++++++++++++++++++++--- examples/example.py | 9 +++ 3 files changed, 123 insertions(+), 19 deletions(-) diff --git a/ROADMAP.md b/ROADMAP.md index 399e649..cc6dc2a 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -15,25 +15,25 @@ This document outlines the planned features and improvements for the `DataBridge - [X] Endpoints: MarketPricesAPi - [X] Endpoints: IncubationApi - [X] Endpoints: RpmeApi -- [ ] Endpoints: SurveysApi -- [ ] Endpoints: XlsFormsApi +- [X] Endpoints: XlsFormsApi +- [X] Endpoints: SurveysApi -### Bug Fixes -- [ ] DPO change for XLSForm -- [ ] Markets GeoJSON response -- [ ] JSON to DataFrame response -- [ ] Market list JSON and CSV ## Future Release -### v1.x.1 -- [ ] Documentation: Enhance documentation and provide more usage examples -- [ ] GitHub Actions linting and testing -- [ ] Test AIMS and RPME endpoints ### v1.1.0 - [ ] R example files - [ ] Handle SSL certificate error +### v1.1.1 +- [ ] Documentation: Enhance documentation and provide more usage examples +- [ ] Automation: GitHub Actions linting and testing +- [ ] Bug fixing: Test AIMS and RPME endpoints +- [ ] Bug fixing: DPO change for XLSForm +- [ ] Bug fixing: Markets GeoJSON response +- [ ] Bug fixing: JSON to DataFrame response +- [ ] Bug fixing: Market list JSON and CSV + ### v1.2.0 - [ ] STATA support - [ ] Fix optional dependencies for STATA diff --git a/data_bridges_knots/client.py b/data_bridges_knots/client.py index ee981ab..9ae9372 100644 --- a/data_bridges_knots/client.py +++ b/data_bridges_knots/client.py @@ -916,6 +916,109 @@ def get_mfi_xls_forms_detailed(self, adm0_code=0, page=1, start_date=None, end_d logger.error(f"Exception when calling XlsFormsApi->m_fi_xls_forms_get: {e}") raise + def get_mfi_surveys_base_data(self, survey_id=None, page=1, page_size=20): + """ + Get data that includes the core Market Functionality Index (MFI) fields only by Survey ID. + + Args: + survey_id (int): Unique identifier for the collected data + page (int): Page number for paged results + page_size (int): Number of items per page + + Returns: + pandas.DataFrame: DataFrame containing MFI base survey data + """ + with data_bridges_client.ApiClient(self.configuration) as api_client: + api_instance = data_bridges_client.SurveysApi(api_client) + env = self.env + + try: + api_response = api_instance.m_fi_surveys_base_data_get( + survey_id=survey_id, + page=page, + page_size=page_size, + env=env + ) + logger.info("Successfully retrieved MFI surveys base data") + return pd.DataFrame(api_response.items) + + except ApiException as e: + logger.error(f"Exception when calling SurveysApi->m_fi_surveys_base_data_get: {e}") + raise + + def get_mfi_surveys_full_data(self, survey_id=None, format='json', page=1, page_size=20): + """ + Get full dataset including all survey fields plus core MFI fields by Survey ID. + + Args: + survey_id (int): Unique identifier for the collected data + format (str): Output format ('json' or 'csv') + page (int): Page number for paged results + page_size (int): Number of items per page + + Returns: + pandas.DataFrame: DataFrame containing complete MFI survey data + """ + with data_bridges_client.ApiClient(self.configuration) as api_client: + api_instance = data_bridges_client.SurveysApi(api_client) + env = self.env + + try: + api_response = api_instance.m_fi_surveys_full_data_get( + survey_id=survey_id, + format=format, + page=page, + page_size=page_size, + env=env + ) + logger.info("Successfully retrieved MFI surveys full data") + return pd.DataFrame(api_response.items) + except ApiException as e: + logger.error(f"Exception when calling SurveysApi->m_fi_surveys_full_data_get: {e}") + raise + + def get_mfi_surveys_processed_data(self, 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 with various aggregation levels and dimensions. + + Args: + survey_id (int): Survey ID + page (int): Page number + page_size (int): Items per page + format (str): Output format + start_date (str): Start date for data collection range + end_date (str): End date for data collection range + adm0_codes (str): Country code + market_id (int): Market identifier + survey_type (str): Type of survey + + Returns: + pandas.DataFrame: DataFrame containing processed MFI survey data + """ + with data_bridges_client.ApiClient(self.configuration) as api_client: + api_instance = data_bridges_client.SurveysApi(api_client) + env = self.env + + try: + api_response = api_instance.m_fi_surveys_processed_data_get( + survey_id=survey_id, + page=page, + page_size=page_size, + format=format, + start_date=start_date, + end_date=end_date, + adm0_codes=adm0_codes, + market_id=market_id, + survey_type=survey_type, + env=env + ) + logger.info("Successfully retrieved MFI surveys processed data") + return pd.DataFrame(api_response.items) + except ApiException as e: + logger.error(f"Exception when calling SurveysApi->m_fi_surveys_processed_data_get: {e}") + raise @@ -926,12 +1029,4 @@ def get_mfi_xls_forms_detailed(self, adm0_code=0, page=1, start_date=None, end_d client = DataBridgesShapes(CONFIG_PATH) - mfi_xls_forms = client.get_mfi_xls_forms(page=1, start_date='2023-01-01', end_date='2023-12-31') - xls_forms = client.get_mfi_xls_forms_detailed( - adm0_code=0, - page=1, - start_date='2023-01-01', - end_date='2023-12-31' -) - print(xls_forms) \ No newline at end of file diff --git a/examples/example.py b/examples/example.py index 9e5d800..5c5d57d 100644 --- a/examples/example.py +++ b/examples/example.py @@ -44,6 +44,15 @@ # Get MFI XLSForm information mfi_xls_forms = client.get_mfi_xls_forms(page=1, start_date='2023-01-01', end_date='2023-12-31') +xls_forms = client.get_mfi_xls_forms_detailed( + adm0_code=0, + page=1, + start_date='2023-01-01', + end_date='2023-12-31' +) + + + #%% FOOD SECURITY DATA # Get IPC and equivalent food insecurity numbers for all countries get_food_security_list = client.get_food_security_list()