Baidu APIaiqicha.baidu.com ↗

"""
Aiqicha Business Intelligence API Client
Comprehensive API for Chinese business intelligence from Aiqicha (Baidu).
Includes company search, details, shareholders, executives, and person lookup.

Get your API key from: https://parse.bot/settings
Note: This API has strict mainland-China-only geo-blocking.
"""

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


class ParseClient:
    """Client for interacting with the Aiqicha Business Intelligence API."""

    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 = "9bb50d87-941e-4c12-b162-4f109781ce67"
        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 in PARSE_API_KEY environment variable")

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

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

        Returns:
            Response data as dictionary

        Raises:
            requests.RequestException: If the API 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 == "GET":
                response = requests.get(url, headers=headers, params=params, timeout=30)
            elif method == "POST":
                response = requests.post(url, headers=headers, json=params, timeout=30)
            else:
                raise ValueError(f"Unsupported HTTP method: {method}")

            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            raise requests.RequestException(f"API request failed: {str(e)}")

    def search_companies(self, query: str) -> Dict[str, Any]:
        """
        Search for companies by name, keyword, or registration number.

        Args:
            query: Search keyword (company name, ID, etc.)

        Returns:
            Response containing list of matching companies with entName and pid
        """
        return self._call("search_companies", method="GET", query=query)

    def get_company_detail(self, pid: str) -> Dict[str, Any]:
        """
        Retrieve detailed information about a specific company by its PID.

        Args:
            pid: Company PID (from search results)

        Returns:
            Response containing company details including basicInfo
        """
        return self._call("get_company_detail", method="GET", pid=pid)

    def get_company_shareholders(self, pid: str) -> Dict[str, Any]:
        """
        Get the shareholder list for a given company.

        Args:
            pid: Company PID

        Returns:
            Response containing list of shareholders with shareholderName and shareholdRatio
        """
        return self._call("get_company_shareholders", method="GET", pid=pid)

    def get_company_executives(self, pid: str) -> Dict[str, Any]:
        """
        Get the list of key executives and management personnel for a company.

        Args:
            pid: Company PID

        Returns:
            Response containing list of executives with name and title
        """
        return self._call("get_company_executives", method="GET", pid=pid)

    def search_people(self, name: str) -> Dict[str, Any]:
        """
        Search for business people/executives by name.

        Args:
            name: Person name

        Returns:
            Response containing list of matching people with name and pid
        """
        return self._call("search_people", method="GET", name=name)

    def get_person_detail(self, pid: str) -> Dict[str, Any]:
        """
        Get detailed profile of a business person.

        Args:
            pid: Person PID (from search results)

        Returns:
            Response containing person details with role and name
        """
        return self._call("get_person_detail", method="GET", pid=pid)


def print_section(title: str) -> None:
    """Print a formatted section header."""
    print(f"\n{'='*70}")
    print(f"  {title}")
    print(f"{'='*70}\n")


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

    # ============================================================================
    # Workflow: Research a company and its key stakeholders
    # ============================================================================

    print_section("STEP 1: Search for Companies")
    print("Searching for 'Baidu' companies...")

    search_result = client.search_companies(query="Baidu")

    if search_result.get("status") == 0 and search_result.get("data", {}).get("list"):
        companies = search_result["data"]["list"]
        print(f"Found {len(companies)} companies:\n")

        for idx, company in enumerate(companies[:3], 1):  # Process top 3 results
            company_name = company.get("entName", "N/A")
            company_pid = company.get("pid", "N/A")
            print(f"  {idx}. {company_name}")
            print(f"     PID: {company_pid}\n")

            # ====================================================================
            # STEP 2: Get detailed information for each company
            # ====================================================================
            print_section(f"STEP 2: Company Details - {company_name}")

            detail_result = client.get_company_detail(pid=company_pid)

            if detail_result.get("status") == 0:
                company_data = detail_result.get("data", {})
                basic_info = company_data.get("basicInfo", {})

                legal_person = basic_info.get("legalPerson", "N/A")
                ent_name = basic_info.get("entName", "N/A")

                print(f"Company Name: {ent_name}")
                print(f"Legal Representative: {legal_person}")
            else:
                print(f"Failed to fetch details: {detail_result.get('msg', 'Unknown error')}")

            # ====================================================================
            # STEP 3: Get shareholders information
            # ====================================================================
            print_section(f"STEP 3: Shareholders - {company_name}")

            shareholders_result = client.get_company_shareholders(pid=company_pid)

            if shareholders_result.get("status") == 0:
                shareholders = shareholders_result.get("data", {}).get("list", [])
                if shareholders:
                    print(f"Total Shareholders: {len(shareholders)}\n")
                    for shareholder in shareholders[:5]:  # Show top 5
                        shareholder_name = shareholder.get("shareholderName", "N/A")
                        shareholding_ratio = shareholder.get("shareholdRatio", "N/A")
                        print(f"  • {shareholder_name}: {shareholding_ratio}")
                else:
                    print("No shareholder information available")
            else:
                print(f"Failed to fetch shareholders: {shareholders_result.get('msg', 'Unknown error')}")

            # ====================================================================
            # STEP 4: Get executives information
            # ====================================================================
            print_section(f"STEP 4: Key Executives - {company_name}")

            executives_result = client.get_company_executives(pid=company_pid)

            if executives_result.get("status") == 0:
                executives = executives_result.get("data", {}).get("list", [])
                if executives:
                    print(f"Total Executives: {len(executives)}\n")
                    for executive in executives[:5]:  # Show top 5
                        exec_name = executive.get("name", "N/A")
                        exec_title = executive.get("title", "N/A")
                        print(f"  • {exec_name}")
                        print(f"    Title: {exec_title}\n")
                else:
                    print("No executive information available")
            else:
                print(f"Failed to fetch executives: {executives_result.get('msg', 'Unknown error')}")

    else:
        print("No companies found or API error")

    # ============================================================================
    # Bonus: Search for a specific person
    # ============================================================================
    print_section("BONUS: Search for a Business Person")
    print("Searching for 'Robin Li'...\n")

    person_search_result = client.search_people(name="Robin Li")

    if person_search_result.get("status") == 0 and person_search_result.get("data", {}).get("list"):
        people = person_search_result["data"]["list"]
        print(f"Found {len(people)} people named 'Robin Li':\n")

        for person in people[:2]:  # Show top 2 results
            person_name = person.get("name", "N/A")
            person_pid = person.get("pid", "N/A")

            print(f"Name: {person_name}")
            print(f"PID: {person_pid}")

            # Get details for this person
            person_detail_result = client.get_person_detail(pid=person_pid)

            if person_detail_result.get("status") == 0:
                person_data = person_detail_result.get("data", {})
                person_role = person_data.get("role", "N/A")
                print(f"Role: {person_role}")
            else:
                print(f"Failed to fetch person details: {person_detail_result.get('msg', 'Unknown error')}")

            print()
    else:
        print("No people found with that name")

    print_section("Workflow Complete")
    print("Successfully demonstrated company and person research workflow!")