Edu APIjgw.aynu.edu.cn ↗

"""
Yinqi Wenyuan Oracle Bone API Client

This module provides a Python client for accessing oracle bone inscription data
from the Yinqi Wenyuan digital platform at Anyang Normal University.

Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for interacting with the Yinqi Wenyuan Oracle Bone API."""

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

        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 = "5a3d513d-906e-4de4-9455-65d043c4f1de"
        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 an API call to the Parse service.

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

        Returns:
            Parsed JSON response as dictionary

        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"}

        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_inscriptions(
        self, query: str, book_code: Optional[str] = None, page: int = 1
    ) -> Dict[str, Any]:
        """
        Search for oracle bone inscriptions in the collection database.

        Args:
            query: Search term for inscription name (e.g. '合', '拼')
            book_code: Optional filter by collection code (e.g. '010001H')
            page: Page number for pagination (default: 1)

        Returns:
            Dictionary with 'items' (inscriptions) and 'pagination' info
        """
        params = {"query": query, "page": page}
        if book_code:
            params["book_code"] = book_code

        return self._call("search_inscriptions", method="GET", **params)

    def search_characters(
        self, query: str, type: int = 1
    ) -> Dict[str, Any]:
        """
        Search for oracle bone characters in the font database.

        Args:
            query: Search term - Chinese character (type=1) or pinyin string (type=3)
            type: Search type - 1 for character lookup, 3 for pinyin lookup (default: 1)

        Returns:
            Dictionary with 'items' containing character objects
        """
        return self._call(
            "search_characters", method="GET", query=query, type=type
        )

    def get_character_detail(self, unicode_id: str) -> Dict[str, Any]:
        """
        Get detailed information for a specific oracle bone character.

        Args:
            unicode_id: Unicode ID of the character (e.g. 'U608C1')

        Returns:
            Dictionary with character details including sources and related characters
        """
        return self._call("get_character_detail", method="GET", unicode_id=unicode_id)

    def get_collections(self) -> Dict[str, Any]:
        """
        List all available oracle bone collections and books.

        Returns:
            Dictionary with 'collections' array containing collection metadata
        """
        return self._call("get_collections", method="GET")

    def get_radicals(self) -> Dict[str, Any]:
        """
        List radicals used for indexing characters in the oracle bone font database.

        Returns:
            Dictionary with 'radicals' array containing radical identifiers
        """
        return self._call("get_radicals", method="GET")


def main():
    """
    Practical workflow demonstrating the Oracle Bone API client.

    This example shows a realistic use case:
    1. Get available collections
    2. Search for inscriptions containing a specific character
    3. For each inscription found, retrieve character details
    4. Display comprehensive information about the findings
    """
    # Initialize the client
    client = ParseClient()

    print("=" * 70)
    print("YINQI WENYUAN ORACLE BONE API - PRACTICAL WORKFLOW")
    print("=" * 70)

    # Step 1: Get available collections
    print("\n[Step 1] Fetching available oracle bone collections...")
    collections_response = client.get_collections()
    collections = collections_response.get("data", {}).get("collections", [])

    print(f"Found {len(collections)} collections:")
    for collection in collections[:5]:  # Show first 5
        print(f"  - {collection['name']} (Code: {collection['code']})")

    if len(collections) > 5:
        print(f"  ... and {len(collections) - 5} more")

    # Step 2: Search for inscriptions with a common oracle bone character
    print("\n[Step 2] Searching for inscriptions containing '合' (he)...")
    search_query = "合"
    inscriptions_response = client.search_inscriptions(
        query=search_query, page=1
    )

    items = inscriptions_response.get("data", {}).get("items", [])
    pagination = inscriptions_response.get("data", {}).get("pagination", {})

    print(
        f"Found {pagination.get('total_count', 0)} total inscriptions "
        f"(showing page {pagination.get('current_page', 1)} of {pagination.get('total_pages', 0)})"
    )
    print(f"Sample inscriptions on this page: {len(items)}")

    # Step 3: Search for the character in the character database
    print(f"\n[Step 3] Looking up character details for '{search_query}'...")
    char_search_response = client.search_characters(query=search_query, type=1)
    characters = char_search_response.get("data", {}).get("items", [])

    print(f"Found {len(characters)} character entry(ies):")

    # Step 4: Get detailed information for each character found
    for idx, char in enumerate(characters[:3], 1):  # Show details for first 3
        unicode_id = char.get("unicode_id")
        meaning = char.get("meaning_traditional", "N/A")
        pinyin = char.get("pinyin", "N/A")
        bone_ref = char.get("bone_reference", "N/A")

        print(f"\n  Character {idx}: {unicode_id}")
        print(f"    Meaning: {meaning}")
        print(f"    Pinyin: {pinyin}")
        print(f"    Oracle Bone Reference: {bone_ref}")

        # Get full details for this character
        if unicode_id:
            try:
                detail_response = client.get_character_detail(unicode_id)
                detail = detail_response.get("data", {})
                sources = detail.get("sources", [])
                related = detail.get("related_chars", "")

                if sources:
                    print(f"    Sources: {len(sources)} reference(s)")
                    for source in sources[:2]:
                        print(
                            f"      - Type {source.get('type_code')}: {source.get('content')}"
                        )
                    if len(sources) > 2:
                        print(f"      ... and {len(sources) - 2} more")

                if related:
                    print(f"    Related Characters: {related[:50]}...")

            except Exception as e:
                print(f"    (Could not retrieve full details: {str(e)})")

    # Step 5: Display inscription sample data
    print("\n[Step 4] Sample inscriptions retrieved:")
    for idx, inscription in enumerate(items[:3], 1):  # Show first 3
        print(f"\n  Inscription {idx}:")
        print(f"    ID: {inscription.get('id')}")
        print(f"    Name: {inscription.get('name')}")
        print(f"    Type: {inscription.get('type')}")
        print(f"    Source: {inscription.get('source')}")
        print(f"    Image: {inscription.get('image_url', 'N/A')[:60]}...")

    print("\n" + "=" * 70)
    print("Workflow complete!")
    print("=" * 70)


if __name__ == "__main__":
    main()