Professional Multi-Currency Converter

Overview

Welcome to the Professional Multi-Currency Converter – a Java application that fetches real-time exchange rates from the European Central Bank via the Frankfurter API! This project is perfect for beginners looking to understand API integration, exception handling, and clean Java architecture.

Features

• Real-time Exchange Rates – Live data from European Central Bank
• Multi-Currency Support – Includes both major and emerging currencies
• Robust Error Handling – Custom exceptions for API failures
• Clean Architecture – Separated service layer and business logic
• User-Friendly CLI – Simple command-line interface
• Professional Standards – Proper User-Agent headers and input validation

Getting Started

Prerequisites

• Java 11 or higher (for HttpClient support)
• Internet connection (for API calls)
• Basic Java knowledge (perfect for learning!)

Installation

1. Clone the repository

   git clone https://github.com/daniel-oyoo/currency-converter.git
   cd currency-converter

2. Compile the Java file

   javac CurrencyApp.java

3. Run the application

   java CurrencyApp

How to Use

1. Launch the application
2. View available currencies (majors & minors)
3. Enter a 3-letter currency code (e.g., EUR, JPY, INR)
4. Enter the amount in USD
5. View the converted amount with live rates!

Example session:

=== PROFESSIONAL MULTI-CURRENCY CONVERTER ===
Available Majors: [EUR, GBP, JPY, CAD, AUD]
Available Minors: [INR, BRL, ZAR, TRY, THB]

Enter Target Currency Code: EUR
Enter Amount in USD: 100
Fetching live rate for EUR...

====================
Result: 100.00 USD = 92.50 EUR
Exchange Rate: 1 USD = 0.9250 EUR
====================

Project Structure

CurrencyApp.java

Technical Details

API Integration

• Uses Java 11+ HttpClient
• Fetches from Frankfurter API (free, no API key needed)
• Implements proper User-Agent headers
• Includes HTTP status code validation

Key Components

1. ApiException – Custom exception for API/network errors
2. CurrencyService – Handles all API communications
3. CurrencyApp – Main class with user interface
4. Input Validation – Prevents invalid currency codes

How to Contribute

We welcome all contributors – especially beginners! Here's how you can help:

Good First Issues

• Add more currency codes
• Improve error messages
• Create a GUI version
• Add historical rate tracking
• Implement unit tests

Contribution Steps

1. Fork this repository
2. Create a branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Contribution Guidelines

• Follow Java naming conventions
• Add comments for new complex logic
• Test your changes before submitting
• Update documentation if needed

Learning Resources

For New Contributors

• Java Basics Tutorial
• Git & GitHub Guide
• API Concepts for Beginners

Project-Specific Concepts

• HttpClient – Java's modern HTTP client
• JSON Parsing – Manual parsing technique
• Exception Handling – Custom exceptions
• API Integration – RESTful service consumption

Troubleshooting

Issue	Solution
"API Error: Received status code 429"	You're being rate-limited. Wait a minute and try again.
"Input Error: Please enter numbers only"	Enter numeric values for amounts (e.g., 100, 50.25)
"Currency not supported"	Use only the currencies listed in the available sets
Compilation errors	Ensure you're using Java 11+

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Frankfurter API for providing free exchange rate data
• European Central Bank for the source data
• All contributors who help improve this project

Support

• Create an issue for bugs or feature requests
• Start a discussion for questions
• Check existing issues before creating new ones

---

If you find this project helpful, please give it a star!

---

Happy Coding!

Built with love for the Java learning community