Bawabatic APIbawabatic.dz ↗

"""
Algeria Public Services Portal API Client
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for accessing the Algeria Public Services Portal API via Parse."""

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

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "50ee29a0-6c16-4377-8e7b-f4bf622c511f"
        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 call to the Parse API.

        Args:
            endpoint: The endpoint name to call
            method: HTTP method (GET or POST)
            **params: Query parameters or request body parameters

        Returns:
            The API response as a 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)
        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()

    def get_homepage(self, lang: str = "en") -> Dict[str, Any]:
        """Fetch the main homepage of the Government Portal of Public Services.

        Args:
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            Portal description and basic metadata
        """
        return self._call("get_homepage", method="GET", lang=lang)

    def list_themes(self, lang: str = "en") -> Dict[str, Any]:
        """Retrieve all available service themes/categories.

        Args:
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            List of theme objects with ID, name, and service count
        """
        return self._call("list_themes", method="GET", lang=lang)

    def get_services_by_theme(self, theme_id: str, lang: str = "en") -> Dict[str, Any]:
        """Retrieve all public services listed under a specific theme.

        Args:
            theme_id: The theme ID
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            Services under the specified theme
        """
        return self._call(
            "get_services_by_theme", method="GET", theme_id=theme_id, lang=lang
        )

    def list_sectors(self, lang: str = "en") -> Dict[str, Any]:
        """Retrieve all ministries/sectors listed on the portal.

        Args:
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            List of sectors with ID and name
        """
        return self._call("list_sectors", method="GET", lang=lang)

    def get_services_by_sector(self, sector_id: str, lang: str = "en") -> Dict[str, Any]:
        """Retrieve all public services listed under a specific ministry/sector.

        Args:
            sector_id: The sector ID
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            Services under the specified sector
        """
        return self._call(
            "get_services_by_sector", method="GET", sector_id=sector_id, lang=lang
        )

    def get_service_detail(self, service_id: str, lang: str = "en") -> Dict[str, Any]:
        """Retrieve full details of a specific public service or procedure.

        Args:
            service_id: The service ID
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            Full details of the service including description, target audience, and metadata
        """
        return self._call(
            "get_service_detail", method="GET", service_id=service_id, lang=lang
        )

    def search_services(self, query: str, lang: str = "en") -> Dict[str, Any]:
        """Search for public services by keyword across all themes and sectors.

        Args:
            query: Search keyword
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            List of services matching the search query
        """
        return self._call("search_services", method="GET", query=query, lang=lang)

    def get_country_info(self, lang: str = "en") -> Dict[str, Any]:
        """Retrieve general country information about Algeria.

        Args:
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            Country information including government type, contact details, and metadata
        """
        return self._call("get_country_info", method="GET", lang=lang)

    def get_important_links(self, lang: str = "en") -> Dict[str, Any]:
        """Retrieve the list of important external government links featured on the portal.

        Args:
            lang: Language code (ar/fr/en). Defaults to 'en'.

        Returns:
            List of important government links
        """
        return self._call("get_important_links", method="GET", lang=lang)


def main():
    """Practical workflow demonstrating the Parse API client."""
    client = ParseClient()

    print("=" * 70)
    print("ALGERIA PUBLIC SERVICES PORTAL - API DEMONSTRATION")
    print("=" * 70)

    print("\n1. FETCHING PORTAL HOMEPAGE")
    print("-" * 70)
    homepage = client.get_homepage(lang="en")
    print(f"Portal: {homepage.get('title', 'N/A')}")
    print(f"Description: {homepage.get('description', 'N/A')}")
    print(f"URL: {homepage.get('url', 'N/A')}")

    print("\n2. FETCHING COUNTRY INFORMATION")
    print("-" * 70)
    country_info = client.get_country_info(lang="en")
    print(f"Official Name: {country_info.get('official_name', 'N/A')}")
    print(f"Government Type: {country_info.get('government', 'N/A')}")
    print(f"Location: {country_info.get('location', 'N/A')}")
    print(f"Operator: {country_info.get('operator', 'N/A')}")
    if "contact" in country_info:
        contact = country_info["contact"]
        print(f"Contact Address: {contact.get('address', 'N/A')}")
        print(f"Contact Email: {contact.get('email', 'N/A')}")

    print("\n3. BROWSING THEMES AND THEIR SERVICES")
    print("-" * 70)
    themes_response = client.list_themes(lang="en")
    total_themes = themes_response.get("total_themes", 0)
    print(f"Total themes available: {total_themes}")

    if themes_response.get("themes"):
        for idx, theme in enumerate(themes_response["themes"][:3], 1):
            theme_id = theme.get("id")
            theme_name = theme.get("name")
            service_count = theme.get("service_count", 0)

            print(f"\n  Theme {idx}: {theme_name} (ID: {theme_id})")
            print(f"  Services in this theme: {service_count}")

            services_response = client.get_services_by_theme(theme_id, lang="en")
            services = services_response.get("services", [])

            if services:
                print(f"  Sample services (first 3):")
                for service in services[:3]:
                    service_name = service.get("name", "N/A")
                    print(f"    - {service_name}")

    print("\n4. SEARCHING FOR SPECIFIC SERVICES")
    print("-" * 70)
    search_keywords = ["passport", "health", "education"]

    for keyword in search_keywords:
        search_results = client.search_services(query=keyword, lang="en")
        results = search_results.get("results", [])
        print(
            f"\nSearch results for '{keyword}': {len(results)} services found"
        )

        if results:
            for service in results[:2]:
                service_name = service.get("name", "N/A")
                print(f"  - {service_name}")

    print("\n5. BROWSING SECTORS (MINISTRIES)")
    print("-" * 70)
    sectors_response = client.list_sectors(lang="en")
    total_sectors = sectors_response.get("total_sectors", 0)
    print(f"Total sectors available: {total_sectors}")

    if sectors_response.get("sectors"):
        for idx, sector in enumerate(sectors_response["sectors"][:3], 1):
            sector_id = sector.get("id")
            sector_name = sector.get("name")

            print(f"\n  Sector {idx}: {sector_name} (ID: {sector_id})")

            sector_services = client.get_services_by_sector(sector_id, lang="en")
            services = sector_services.get("services", [])

            if services:
                print(f"  Services in this sector (first 3):")
                for service in services[:3]:
                    service_id = service.get("id")
                    service_name = service.get("name", "N/A")
                    print(f"    - {service_name} (ID: {service_id})")

                    if service_id and idx == 1:
                        detail = client.get_service_detail(service_id, lang="en")
                        description = detail.get("description", "No description")
                        target_audience = detail.get("target_audience", [])

                        print(f"      Description: {description[:100]}...")
                        if target_audience:
                            print(f"      Target Audience: {', '.join(target_audience)}")

    print("\n6. IMPORTANT GOVERNMENT LINKS")
    print("-" * 70)
    links_response = client.get_important_links(lang="en")
    links = links_response.get("links", [])

    if links:
        print(f"Featured government links ({len(links)} total):")
        for link in links[:5]:
            link_name = link.get("name", "N/A")
            link_url = link.get("url", "N/A")
            print(f"  - {link_name}: {link_url}")

    print("\n" + "=" * 70)
    print("API DEMONSTRATION COMPLETED SUCCESSFULLY")
    print("=" * 70)


if __name__ == "__main__":
    main()