Careem APIcareem.com ↗

"""
Careem Exchange Rates API Client
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional, List, Dict, Any


class ParseClient:
    """Client for interacting with the Parse API."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.
        
        Args:
            api_key: API key for authentication. If not provided, uses PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "0d4ff692-d857-41e6-a357-78f9612fe2c9"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key must be provided or set as PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make an API call to the Parse endpoint.
        
        Args:
            endpoint: The endpoint name (e.g., 'get_exchange_rates')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters to send with the request
            
        Returns:
            Parsed JSON response from the API
            
        Raises:
            requests.exceptions.RequestException: If the request fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        try:
            if method.upper() == "GET":
                response = requests.get(url, headers=headers, params=params)
            elif method.upper() == "POST":
                response = requests.post(url, headers=headers, json=params)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")
            
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f"API request failed: {e}")
            raise

    def get_exchange_rates(self, destination_currency: Optional[str] = None) -> Dict[str, Any]:
        """
        Retrieve current AED exchange rates for all supported remittance corridors.
        
        Args:
            destination_currency: Optional filter by destination currency code (ISO 4217).
                                 Examples: INR, GBP, PKR, PHP, BDT, SAR, EGP, TRY, USD, JOD, CAD, EUR
        
        Returns:
            Dictionary containing source currency, corridors, and total count.
            Each corridor includes exchange rate, fee, min/max amounts, and delivery time.
        """
        params = {}
        if destination_currency:
            params["destination_currency"] = destination_currency
        
        return self._call("get_exchange_rates", method="GET", **params)


def format_corridor_info(corridor: Dict[str, Any]) -> str:
    """Format corridor information for display."""
    return (
        f"  {corridor['destination_country']} ({corridor['destination_currency']}): "
        f"Rate: {corridor['exchange_rate']}, "
        f"Fee: AED {corridor['fee']} (on transfers ≥ AED {corridor['fee_threshold_amount']}), "
        f"Send: AED {corridor['min_amount']}-{corridor['max_amount']}, "
        f"Delivery: {corridor['estimated_time']}"
    )


def main():
    """Practical workflow demonstrating the Careem Exchange Rates API."""
    
    # Initialize the client
    client = ParseClient()
    
    print("=" * 80)
    print("CAREEM EXCHANGE RATES API - PRACTICAL WORKFLOW")
    print("=" * 80)
    
    # Use case 1: Get all available corridors
    print("\n1. Fetching all available remittance corridors from AED...")
    all_rates = client.get_exchange_rates()
    print(f"   Source Currency: {all_rates['source_currency']}")
    print(f"   Total Corridors Available: {all_rates['total_corridors']}")
    print("\n   First 5 corridors:")
    for corridor in all_rates['corridors'][:5]:
        print(format_corridor_info(corridor))
    
    # Use case 2: Find specific corridors for popular destinations
    popular_destinations = ["INR", "PKR", "PHP", "USD", "EUR"]
    print(f"\n2. Checking exchange rates for popular destinations: {', '.join(popular_destinations)}")
    
    destination_rates = {}
    for currency in popular_destinations:
        try:
            rates = client.get_exchange_rates(destination_currency=currency)
            if rates['corridors']:
                destination_rates[currency] = rates['corridors'][0]
                corridor = rates['corridors'][0]
                print(f"\n   {currency}:")
                print(format_corridor_info(corridor))
        except Exception as e:
            print(f"\n   {currency}: Error retrieving rates - {e}")
    
    # Use case 3: Analyze sending scenarios
    print("\n3. Analyzing transfer scenarios for different amounts:")
    send_amounts = [100, 500, 1000, 5000]
    
    if "INR" in destination_rates:
        corridor = destination_rates["INR"]
        print(f"\n   Sending AED to INR (Exchange Rate: {corridor['exchange_rate']}):")
        print(f"   Fee applies on transfers ≥ AED {corridor['fee_threshold_amount']}")
        
        for amount in send_amounts:
            if corridor['min_amount'] <= amount <= corridor['max_amount']:
                fee = corridor['fee'] if amount >= corridor['fee_threshold_amount'] else 0
                net_send = amount - fee
                received_inr = net_send * corridor['exchange_rate']
                print(f"\n   • Send AED {amount}:")
                print(f"     Fee: AED {fee}")
                print(f"     Net to Convert: AED {net_send}")
                print(f"     You Receive: ₹ {received_inr:.2f}")
            else:
                status = "Below" if amount < corridor['min_amount'] else "Above"
                limit = corridor['min_amount'] if amount < corridor['min_amount'] else corridor['max_amount']
                print(f"\n   • Send AED {amount}: ❌ {status} limit (AED {limit})")
    
    # Use case 4: Find best rates for a specific amount
    print("\n4. Finding best exchange rates for sending AED 1000:")
    amount_to_send = 1000
    best_value_corridors = []
    
    for corridor in all_rates['corridors']:
        if corridor['min_amount'] <= amount_to_send <= corridor['max_amount']:
            fee = corridor['fee'] if amount_to_send >= corridor['fee_threshold_amount'] else 0
            net_send = amount_to_send - fee
            received = net_send * corridor['exchange_rate']
            best_value_corridors.append({
                'corridor': corridor,
                'total_received': received,
                'effective_rate': received / amount_to_send
            })
    
    # Sort by total received (descending)
    best_value_corridors.sort(key=lambda x: x['total_received'], reverse=True)
    
    print(f"\n   Top 5 best value destinations for AED {amount_to_send}:")
    for i, item in enumerate(best_value_corridors[:5], 1):
        corridor = item['corridor']
        fee = amount_to_send - (item['total_received'] / corridor['exchange_rate'])
        print(f"\n   {i}. {corridor['destination_country']} ({corridor['destination_currency']})")
        print(f"      You Receive: {item['total_received']:.2f} {corridor['destination_currency']}")
        print(f"      Fee: AED {fee:.2f}")
        print(f"      Delivery: {corridor['estimated_time']}")
    
    print("\n" + "=" * 80)


if __name__ == "__main__":
    main()