Gov APIncar.gov.sa ↗

"""
NCAR Saudi Arabia API Client
Access to Saudi National Center for Archives and Records data.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for NCAR Saudi Arabia API."""

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

        Args:
            api_key: API key for authentication. Defaults to PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "635962d4-1cf3-4667-8967-7fa96e07c2f1"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        if not self.api_key:
            raise ValueError("API key required. Set PARSE_API_KEY env var or pass api_key parameter.")

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

        Args:
            endpoint: API endpoint name
            method: HTTP method (GET or POST)
            **params: Query/body parameters

        Returns:
            API response 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 == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "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 search_rules_and_regulations(
        self,
        page: int = 1,
        limit: int = 10,
        sort_column: str = "IsTranslated",
        sort_order: str = "DESC"
    ) -> Dict[str, Any]:
        """
        Search for Saudi rules and regulations with pagination and sorting.

        Args:
            page: Page number (default: 1)
            limit: Number of results per page (default: 10)
            sort_column: Column to sort by (default: IsTranslated)
            sort_order: Sort order ASC/DESC (default: DESC)

        Returns:
            Search results containing data array and metadata
        """
        return self._call(
            "search_rules_and_regulations",
            method="GET",
            page=page,
            limit=limit,
            sort_column=sort_column,
            sort_order=sort_order
        )

    def get_regulation_details(self, doc_id: str) -> Dict[str, Any]:
        """
        Get full details of a specific regulation by its document ID.

        Args:
            doc_id: The encrypted document ID

        Returns:
            Regulation details including title, summary, and attachments
        """
        return self._call(
            "get_regulation_details",
            method="GET",
            doc_id=doc_id
        )

    def search_conventions_and_treaties(
        self,
        page: int = 1,
        limit: int = 10,
        sort_column: str = "IsTranslated",
        sort_order: str = "DESC"
    ) -> Dict[str, Any]:
        """
        Search for Saudi international conventions and treaties.

        Args:
            page: Page number (default: 1)
            limit: Number of results per page (default: 10)
            sort_column: Column to sort by (default: IsTranslated)
            sort_order: Sort order ASC/DESC (default: DESC)

        Returns:
            Search results containing conventions and treaties
        """
        return self._call(
            "search_conventions_and_treaties",
            method="GET",
            page=page,
            limit=limit,
            sort_column=sort_column,
            sort_order=sort_order
        )

    def search_um_alqura_newspaper(
        self,
        page: int = 1,
        limit: int = 8,
        sort_order: str = "DESC"
    ) -> Dict[str, Any]:
        """
        Search for Um Al-Qura newspaper issues.

        Args:
            page: Page number (default: 1)
            limit: Number of results per page (default: 8)
            sort_order: Sort order ASC/DESC (default: DESC)

        Returns:
            Newspaper issues with dates and versions
        """
        return self._call(
            "search_um_alqura_newspaper",
            method="GET",
            page=page,
            limit=limit,
            sort_order=sort_order
        )

    def global_search(self, query: str) -> Dict[str, Any]:
        """
        Perform a global site search across all content types.

        Args:
            query: Search keyword

        Returns:
            Search results across magazines, news, and other content
        """
        return self._call(
            "global_search",
            method="POST",
            query=query
        )

    def get_regions_coding(self) -> Dict[str, Any]:
        """
        Get the hierarchy of administrative regions coding.

        Returns:
            Array of regions with IDs and names
        """
        return self._call(
            "get_regions_coding",
            method="GET"
        )

    def get_governmental_coding(self, name: str = "") -> Dict[str, Any]:
        """
        Search for governmental entity coding data.

        Args:
            name: Agency name to filter by (optional)

        Returns:
            Array of governmental entities with IDs and names
        """
        return self._call(
            "get_governmental_coding",
            method="POST",
            name=name
        )


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

    print("=" * 70)
    print("NCAR Saudi Arabia API - Practical Workflow Example")
    print("=" * 70)

    # Step 1: Search for regulations
    print("\n[1] Searching for rules and regulations (first 5 results)...")
    regulations_result = client.search_rules_and_regulations(page=1, limit=5)

    if regulations_result.get("status") == 1:
        regulations = regulations_result.get("data", [])
        total_count = regulations_result.get("dataLength", 0)
        print(f"✓ Found {total_count} total regulations. Showing {len(regulations)} results:\n")

        for i, reg in enumerate(regulations, 1):
            title = reg.get("title_en", "N/A")
            number = reg.get("number", "N/A")
            date = reg.get("approve_date", "N/A")
            doc_id = reg.get("id", "")

            print(f"  {i}. {title}")
            print(f"     Number: {number} | Date: {date}")

            # Step 2: Get detailed information for the first regulation
            if i == 1 and doc_id:
                print(f"\n[2] Getting detailed information for first regulation (ID: {doc_id[:20]}...)...")
                try:
                    details = client.get_regulation_details(doc_id)
                    if details.get("status") == 1:
                        data = details.get("data", {})
                        summary = data.get("summery_en", "No summary available")
                        print(f"✓ Summary: {summary[:150]}..." if len(summary) > 150 else f"✓ Summary: {summary}")
                except Exception as e:
                    print(f"⚠ Could not fetch details: {str(e)}")
            print()

    # Step 3: Search for conventions and treaties
    print("[3] Searching for international conventions and treaties (first 3 results)...")
    conventions_result = client.search_conventions_and_treaties(page=1, limit=3)

    if conventions_result.get("status") == 1:
        conventions = conventions_result.get("data", [])
        total_count = conventions_result.get("dataLength", 0)
        print(f"✓ Found {total_count} total conventions. Showing {len(conventions)} results:\n")

        for i, conv in enumerate(conventions, 1):
            title = conv.get("title_en", "N/A")
            print(f"  {i}. {title}")
        print()

    # Step 4: Search Um Al-Qura newspaper
    print("[4] Searching Um Al-Qura newspaper (latest 3 issues)...")
    newspaper_result = client.search_um_alqura_newspaper(page=1, limit=3)

    if newspaper_result.get("status") == 1:
        issues = newspaper_result.get("data", [])
        total_count = newspaper_result.get("dataLength", 0)
        print(f"✓ Found {total_count} total newspaper issues. Showing {len(issues)} results:\n")

        for i, issue in enumerate(issues, 1):
            date = issue.get("date", "N/A")
            version = issue.get("version", "N/A")
            issue_id = issue.get("id", "N/A")
            print(f"  {i}. Issue Date: {date} | Version: {version} | ID: {issue_id}")
        print()

    # Step 5: Global search example
    print("[5] Performing global search for 'labor'...")
    search_result = client.global_search(query="labor")

    if search_result.get("status") == 1:
        data = search_result.get("data", {})
        news = data.get("news", [])
        magazines = data.get("magazines", [])
        print(f"✓ Global search completed")
        print(f"  - News items found: {len(news)}")
        print(f"  - Magazine items found: {len(magazines)}")
        print()

    # Step 6: Get administrative regions
    print("[6] Fetching administrative regions coding...")
    regions_result = client.get_regions_coding()

    if regions_result.get("status") == 1:
        regions = regions_result.get("data", [])
        print(f"✓ Found {len(regions)} regions:\n")
        for i, region in enumerate(regions[:5], 1):
            name = region.get("name_ar", "N/A")
            region_id = region.get("id", "N/A")
            print(f"  {i}. ID: {region_id} | Name (AR): {name}")
        if len(regions) > 5:
            print(f"  ... and {len(regions) - 5} more regions")
        print()

    # Step 7: Get governmental entities
    print("[7] Fetching governmental entity coding...")
    gov_result = client.get_governmental_coding()

    if gov_result.get("status") == 1:
        entities = gov_result.get("data", [])
        print(f"✓ Found {len(entities)} governmental entities:\n")
        for i, entity in enumerate(entities[:5], 1):
            name = entity.get("name_ar", "N/A")
            entity_id = entity.get("id", "N/A")
            print(f"  {i}. ID: {entity_id} | Name (AR): {name}")
        if len(entities) > 5:
            print(f"  ... and {len(entities) - 5} more entities")
        print()

    print("=" * 70)
    print("Workflow completed successfully!")
    print("=" * 70)


if __name__ == "__main__":
    main()