Fazaa APIfazaa.com ↗

"""
Fazaa API Client - Parse.bot Integration

Access offers, categories, locations, and special services on Fazaa.ae.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for Fazaa API via Parse.bot scraper service."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse client.

        Args:
            api_key: API key for Parse.bot. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "d0159518-70f3-455a-ad7a-d2cb5f42cc2e"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

    def _call(
        self, endpoint: str, method: str = "POST", **params
    ) -> Dict[str, Any]:
        """
        Make a request to the Parse API.

        Args:
            endpoint: The endpoint name (e.g., 'search_offers')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters

        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {"X-API-Key": self.api_key, "Content-Type": "application/json"}

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        else:
            response = requests.post(url, headers=headers, json=params)

        response.raise_for_status()
        return response.json()

    def search_offers(
        self,
        category: Optional[str] = None,
        query: Optional[str] = None,
        city_id: Optional[str] = None,
        latitude: Optional[float] = None,
        longitude: Optional[float] = None,
        page: int = 0,
        size: int = 20,
    ) -> Dict[str, Any]:
        """
        Search for offers with filters like category, city, keyword, and coordinates.

        Args:
            category: Category slug (e.g., 'new-offers', 'dining')
            query: Search keyword
            city_id: City ID for filtering
            latitude: Latitude for geolocation search
            longitude: Longitude for geolocation search
            page: Page number (0-indexed)
            size: Results per page

        Returns:
            Dictionary with 'content' (list of offers) and 'total' count
        """
        params = {
            k: v
            for k, v in {
                "category": category,
                "query": query,
                "city_id": city_id,
                "latitude": latitude,
                "longitude": longitude,
                "page": page,
                "size": size,
            }.items()
            if v is not None
        }
        return self._call("search_offers", method="GET", **params)

    def get_offer_details(self, slug: str) -> Dict[str, Any]:
        """
        Get full details of a specific offer using its slug.

        Args:
            slug: The offer slug (e.g., 'indish-indian-restaurant')

        Returns:
            Dictionary with offer details including slug, id, partner, and localData
        """
        return self._call("get_offer_details", method="GET", slug=slug)

    def list_categories(self) -> Dict[str, Any]:
        """
        List all available offer categories.

        Returns:
            Dictionary with 'categories' array containing category objects
        """
        return self._call("list_categories", method="GET")

    def list_cities(self) -> Dict[str, Any]:
        """
        List all available cities grouped by country.

        Returns:
            Dictionary with 'countries' array containing cities
        """
        return self._call("list_cities", method="GET")

    def get_membership_benefits(self) -> Dict[str, Any]:
        """
        Retrieve membership tiers and their associated benefits.

        Returns:
            Dictionary with pageName and localData containing benefit details
        """
        return self._call("get_membership_benefits", method="GET")

    def get_used_cars(self) -> Dict[str, Any]:
        """
        Retrieve listings for Fazaa used cars.

        Returns:
            Dictionary with 'content' array of car listings
        """
        return self._call("get_used_cars", method="GET")

    def get_long_term_car_lease(self) -> Dict[str, Any]:
        """
        Retrieve long-term car lease options.

        Returns:
            Dictionary with 'content' array of lease options
        """
        return self._call("get_long_term_car_lease", method="GET")

    def get_daily_rental(self) -> Dict[str, Any]:
        """
        Retrieve daily car rental offers.

        Returns:
            Dictionary with 'content' array of rental offers
        """
        return self._call("get_daily_rental", method="GET")

    def get_amakin(self) -> Dict[str, Any]:
        """
        Retrieve Fazaa Amakin (places/venues) listings.

        Returns:
            Dictionary with 'content' array of amakin offers
        """
        return self._call("get_amakin", method="GET")

    def find_on_map(self, latitude: float, longitude: float) -> Dict[str, Any]:
        """
        Search for partners/offers near a location.

        Args:
            latitude: Latitude coordinate
            longitude: Longitude coordinate

        Returns:
            Dictionary with 'results' array of nearby locations/partners
        """
        return self._call("find_on_map", method="GET", latitude=latitude, longitude=longitude)


if __name__ == "__main__":
    # Initialize client with API key
    client = ParseClient()

    print("=" * 70)
    print("FAZAA API - PRACTICAL WORKFLOW EXAMPLE")
    print("=" * 70)

    # Step 1: List all categories to understand what's available
    print("\n1. Fetching available offer categories...")
    categories_response = client.list_categories()
    categories = categories_response.get("categories", [])
    print(f"   Found {len(categories)} categories:")
    for cat in categories[:5]:  # Show first 5
        print(f"   - {cat.get('categoryInternalName')} (slug: {cat.get('categorySlug')})")

    # Step 2: Get cities to understand location options
    print("\n2. Fetching available cities...")
    cities_response = client.list_cities()
    countries = cities_response.get("countries", [])
    uae = next((c for c in countries if "Emirates" in c.get("name", "")), None)
    if uae:
        cities = uae.get("cities", [])
        print(f"   Found {len(cities)} cities in UAE:")
        for city in cities[:3]:  # Show first 3
            print(f"   - {city.get('internalName')} (id: {city.get('id')})")
        dubai_id = cities[0].get("id") if cities else None
    else:
        dubai_id = None
        print("   UAE not found in available countries")

    # Step 3: Search for dining offers in Dubai
    if dubai_id:
        print(f"\n3. Searching for dining offers in Dubai...")
        search_response = client.search_offers(
            category="dining", city_id=dubai_id, size=5
        )
        offers = search_response.get("content", [])
        total = search_response.get("total", 0)
        print(f"   Found {total} dining offers (showing {len(offers)}):")

        # Step 4: Get detailed information for each offer
        print("\n4. Retrieving detailed information for offers...")
        for offer in offers:
            offer_slug = offer.get("slug")
            offer_title = offer.get("title", "Unknown")
            partner_name = offer.get("partnerName", "Unknown Partner")

            if offer_slug:
                try:
                    details = client.get_offer_details(offer_slug)
                    local_data = details.get("localData", {})
                    en_data = local_data.get("en", {})
                    description = en_data.get("description", "No description")[:60]
                    partner_info = details.get("partner", {})
                    partner_link = partner_info.get("partnerLink", "No link")

                    print(f"\n   Offer: {offer_title}")
                    print(f"   Partner: {partner_name}")
                    print(f"   Link: {partner_link}")
                    print(f"   Description: {description}...")
                except requests.exceptions.RequestException as e:
                    print(f"\n   Offer: {offer_title}")
                    print(f"   Partner: {partner_name}")
                    print(f"   (Could not retrieve full details: {e})")

    # Step 5: Search by location (find offers near specific coordinates)
    print("\n5. Finding offers near Dubai coordinates (25.2048, 55.2708)...")
    try:
        map_response = client.find_on_map(latitude=25.2048, longitude=55.2708)
        nearby = map_response.get("results", [])
        print(f"   Found {len(nearby)} nearby locations/partners:")
        for location in nearby[:3]:  # Show first 3
            name = location.get("name", "Unknown")
            lat = location.get("lat", "N/A")
            lon = location.get("lon", "N/A")
            print(f"   - {name} ({lat}, {lon})")
    except requests.exceptions.RequestException as e:
        print(f"   Could not find map results: {e}")

    # Step 6: Get membership benefits information
    print("\n6. Fetching membership benefits...")
    try:
        benefits_response = client.get_membership_benefits()
        page_name = benefits_response.get("pageName", "Unknown")
        print(f"   Page: {page_name}")
        local_data = benefits_response.get("localData", {})
        en_content = local_data.get("en", {}).get("pageContent", "No content")[:100]
        print(f"   Content: {en_content}...")
    except requests.exceptions.RequestException as e:
        print(f"   Could not fetch benefits: {e}")

    print("\n" + "=" * 70)
    print("WORKFLOW COMPLETE")
    print("=" * 70)