Merge pull request #6 from WFP-VAM/feature/surveyApi

feature: add SurveyApi endpoints

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

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)

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()