Merge pull request #5 from WFP-VAM/dev

DataBridges API 5.0 Endpoints

.gitignore

@@ -168,6 +168,7 @@ data_bridges_api_config.yaml
 .Rhistory
 *.Rproj
 *.yaml
-sandbox.py
+sandbox.*
 *.csv
-.vscode 
+.vscode 
+*.code-workspace

README.md

@@ -4,22 +4,35 @@ This Python module allows you to get data from the WFP Data Bridges API, includi
 
 ## Installation
 
-> NB This is the dev version of the data_bridges_knots and API client package, it is frequently updated yet not stable.
+> NB This is the development version of the data_bridges_knots and API client package, it is frequently updated yet not stable.
 
 You can install the `data_bridges_knots` package using `pip` and the Git repository URL:
 
 ```
-pip install git+https://github.com/WFP-VAM/DataBridgesKnots.git
+pip install --force-reinstall git+https://github.com/WFP-VAM/DataBridgesKnots.git@dev
+```
+
+STATA and R users will also need the appropriate optional dependencies to use this package in their respective software. To install the package with these dependencies, use the following command:
+
+***STATA users***
+```
+pip install git+https://github.com/WFP-VAM/DataBridgesKnots.git#egg=data_bridges_knots[STATA]
+```
+
+***R users***
+```
+pip install git+https://github.com/WFP-VAM/DataBridgesusKnots.git#egg=data_bridges_knots[R]
 ```
 
 ## Configuration
 1. Create a ```data_bridges_api_config.yaml``` in the main folder you're running your core from.
 2. The structure of the file is: 
-    ```
+    ```yaml
     NAME: ''
     VERSION : ''
     KEY: ''
     SECRET: ''
+    DATA_BRIDGES_API_KEY = ''
     SCOPES:
     - ''
     - ''
@@ -29,7 +42,7 @@ pip install git+https://github.com/WFP-VAM/DataBridgesKnots.git
 3. External users can reach out to [[email protected]](mailto:[email protected]) for support on getting the API credentials.
 
 ### Python
-Run the following code to extract household survey data. 
+Run the following code to extract commoditiy data. 
 
 ```python
 
@@ -39,18 +52,11 @@ CONFIG_PATH = r"data_bridges_api_config.yaml"
 
 client = DataBridgesShapes(CONFIG_PATH)
 
-#%% XSLForm definition and Household dataset
-
-CONGO_CFSVA = {
-    'questionnaire': 1509,
-    'dataset': 3094
-}
-# get household survey data  
-survey_data = client.get_household_survey(survey_id=CONGO_CFSVA["dataset"], access_type='full')
-# get XLSForm data
-questionnaire = client.get_household_questionnaire(CONGO_CFSVA["questionnaire"])
+# COMMODITY DATA
+commodity_units_list = client.get_commodity_units_list(country_code="TZA", commodity_unit_name="Kg", page=1, format='json')
 
 ```
+Additional examples are in the [examples](https://github.com/WFP-VAM/DataBridgesKnots/tree/main/examples) folder.
 
 ## Contributing
 Contributions are welcome! Please open an issue or submit a pull request if you have any improvements or bug fixes.

ROADMAP.md

@@ -1,62 +1,46 @@
-# Roadmap for DataBridgesUtils
-
-This document outlines the planned features and improvements for the `DataBridgesUtils` package, which provides a wrapper for the WFP Data Bridges API.
-
-## Upcoming Release: 0.1.0 (DEV)
-
-### Wrapper Endpoints
-
-The following endpoints will be added or improved in the upcoming release:
-
-- [X] Exchange rates 
-- [X] Food security (IPC)
-- [X] GORP (Global Operational Response Plan)
-- [X] Market prices
-- [X] Surveys
-- [X] XSL Forms
-
-### Wrapper Endpoints
-- [X] Get variable labels
-- [X] Get value labels
-- [ ] Output dta with value and variable labels
-
-### Examples and Documentation
-
-- [X] Provide an example file in Python demonstrating the usage of available endpoints
-- [X] Provide an example file in STATA demonstrating the usage of available endpoints
-  - [ ] Test
-- [ ] Provide an example file in R demonstrating the usage of available endpoints
-  - [ ] Test
-- [X] Update the README file with Python usage examples
-- [X] Add documentation for STATA users in the README file
-
-### Repository Setup
-
-- [X] Create a GitHub repository for the `DataBridgesUtils` package
-- [X] Configure optional dependencies in the project files
-- [X] Set up the package installation process
-
-## Improvements (1.1.0)
-
-## Bug fixing
-- [ ] DPO change for GORP
+# Roadmap for DataBridgesKnots
+
+This document outlines the planned features and improvements for the `DataBridgesKnots` package, which provides a wrapper for the WFP Data Bridges API.
+
+## Upcoming Release: 1.0.0 (DataBridges API v5.0)
+
+### New Features
+- [ ] Update setup.py and pyproject.toml to include DataBridges API v5.0
+- [X] Endpoints: CommoditiesApis
+- [X] Endpoints: CurrencyApi
+- [X] Endpoints: EconomicDataApi
+- [X] Endpoints: MarketsApi
+- [X] Endpoints: FoodSecurityApi
+- [X] Endpoints: GorpApi
+- [X] Endpoints: MarketPricesAPi
+- [X] Endpoints: IncubationApi
+- [X] Endpoints: RpmeApi
+- [ ] Endpoints: SurveysApi
+- [ ] Endpoints: XlsFormsApi
+
+### Bug Fixes
 - [ ] DPO change for XLSForm
-- [ ] Fix optional dependencies for STATA
+- [ ] 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
 
-## Wrapper points
-- [ ] Economic data
-- [ ] Commodities
-- [ ] Commodity units
-- [ ] Markets
-- [ ] RPME (Resource Planning and Monitoring Environment)
-
-## Future Releases (2.0.0)
+### v1.2.0 
+- [ ] STATA support
+- [ ] Fix optional dependencies for STATA
 
-- [ ] Improve error handling and logging
-- [ ] Add unit tests and integration tests
-- [ ] Enhance documentation and provide more usage examples
-- [ ] Optimize performance and improve code efficiency
-- [ ] Implement additional features based on user feedback and requirements
+## Future Releases (2.0.0 and beyond)
+- Testing: Unit testing
+- Testing: Improve error handling and logging
+- Refactoring: Optimize performance and improve code efficiency
 
 Please note that this roadmap is subject to change, and the priorities may be adjusted based on the project's needs and available resources.

data_bridges_api_config_sample.yaml

@@ -1,7 +1,8 @@
-NAME: ''
-VERSION : ''
-KEY: ''
-SECRET: ''
-SCOPES:
+NAME: 'name-of-the-application'
+VERSION : '5.0.0'
+KEY: '' # WFP API Gateway API Key
+SECRET: '' # WFP API Gateway API Secret
+DATABRIDGES_API_KEY = '' # WFP DataBridges API Key (required for household data)
+SCOPES: # WFP DataBridges API Scopes (required for restricted endpoints)
  - ''
  - ''