DatasheetCatalog APIdatasheetcatalog.com ↗

"""
Datasheet Catalog API Client
API for retrieving electronic component datasheets, manufacturers, and categories.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for the Datasheet Catalog 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 = "027b2f76-cacf-481b-9203-dace127d74c8"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key not provided and PARSE_API_KEY environment variable not set")
    
    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make an API call to the Parse endpoint.
        
        Args:
            endpoint: The endpoint name (e.g., 'search_datasheets')
            method: HTTP method ('GET' or 'POST')
            **params: Parameters to send with the request
            
        Returns:
            Response JSON as a dictionary
            
        Raises:
            requests.RequestException: If the API call fails
        """
        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 search_datasheets(self, query: str, page: int = 1) -> Dict[str, Any]:
        """
        Search for datasheets by part name, description, or keyword.
        
        Args:
            query: Search keyword or part number
            page: Page number for pagination (default: 1)
            
        Returns:
            Dictionary with 'query', 'page', and 'results' list
        """
        return self._call("search_datasheets", method="GET", query=query, page=page)
    
    def get_datasheet_detail(self, url: str) -> Dict[str, Any]:
        """
        Get detailed information for a specific component datasheet.
        
        Args:
            url: URL of the component detail page
            
        Returns:
            Dictionary with 'part_name', 'detail_url', 'manufacturers', and 'related_parts'
        """
        return self._call("get_datasheet_detail", method="GET", url=url)
    
    def get_manufacturer_list(self) -> Dict[str, Any]:
        """
        Retrieve the full list of all manufacturers indexed in the catalog.
        
        Returns:
            Dictionary with 'manufacturers' list
        """
        return self._call("get_manufacturer_list", method="GET")
    
    def get_manufacturer_components(self, manufacturer_slug: str, page: int = 1) -> Dict[str, Any]:
        """
        Get all datasheets/components listed for a specific manufacturer.
        
        Args:
            manufacturer_slug: Manufacturer slug from get_manufacturer_list
            page: Page number for pagination (default: 1)
            
        Returns:
            Dictionary with 'manufacturer', 'page', and 'components' list
        """
        return self._call("get_manufacturer_components", method="GET", 
                         manufacturer_slug=manufacturer_slug, page=page)
    
    def get_category_list(self) -> Dict[str, Any]:
        """
        Retrieve the full hierarchical list of component categories/functions.
        
        Returns:
            Dictionary with 'categories' list
        """
        return self._call("get_category_list", method="GET")
    
    def get_category_components(self, category_slug: str) -> Dict[str, Any]:
        """
        Get datasheets listed under a specific component category/function.
        
        Args:
            category_slug: Category slug from get_category_list
            
        Returns:
            Dictionary with 'category' and 'components' list
        """
        return self._call("get_category_components", method="GET", category_slug=category_slug)


def main():
    """Practical workflow example: search for components and retrieve detailed information."""
    
    # Initialize the client
    client = ParseClient()
    
    # Workflow 1: Search for a component and get details for top results
    print("=" * 80)
    print("WORKFLOW: Search for Timer Components and Get Detailed Datasheets")
    print("=" * 80)
    
    search_query = "NE555"
    print(f"\n1. Searching for '{search_query}'...")
    search_results = client.search_datasheets(query=search_query, page=1)
    
    print(f"   Found {len(search_results['results'])} results")
    
    # Get details for the first few results
    for i, component in enumerate(search_results['results'][:2], 1):
        print(f"\n   [{i}] {component['part_name']} by {component['manufacturer']}")
        print(f"       Description: {component['description']}")
        
        # Fetch detailed information including PDF links
        detail_url = component['detail_url']
        print(f"\n       Fetching detailed datasheet information...")
        
        try:
            details = client.get_datasheet_detail(url=detail_url)
            
            print(f"       Found {len(details['manufacturers'])} manufacturer(s) with PDFs:")
            for mfg in details['manufacturers']:
                print(f"         - {mfg['manufacturer']}: {mfg['description']}")
                print(f"           PDF: {mfg['pdf_url']}")
            
            if details['related_parts']:
                print(f"       Related parts: {', '.join([p['part_name'] for p in details['related_parts']])}")
        except requests.RequestException as e:
            print(f"       Error fetching details: {e}")
    
    # Workflow 2: Browse components by manufacturer
    print("\n" + "=" * 80)
    print("WORKFLOW: Browse Components by Manufacturer")
    print("=" * 80)
    
    print("\n2. Getting list of manufacturers...")
    manufacturers = client.get_manufacturer_list()
    
    # Show first 3 manufacturers
    print(f"   Found {len(manufacturers['manufacturers'])} manufacturers")
    print("   Showing first 3:")
    
    for i, mfg in enumerate(manufacturers['manufacturers'][:3], 1):
        print(f"\n   [{i}] {mfg['name']}")
        
        # Get components from this manufacturer
        components_data = client.get_manufacturer_components(
            manufacturer_slug=mfg['slug'], 
            page=1
        )
        
        print(f"       Components on page 1: {len(components_data['components'])}")
        for comp in components_data['components'][:2]:
            print(f"         - {comp['part_name']}: {comp['description']}")
    
    # Workflow 3: Browse by category
    print("\n" + "=" * 80)
    print("WORKFLOW: Browse Components by Category")
    print("=" * 80)
    
    print("\n3. Getting list of categories...")
    categories = client.get_category_list()
    
    print(f"   Found {len(categories['categories'])} categories")
    print("   Showing first 2:")
    
    for i, category in enumerate(categories['categories'][:2], 1):
        print(f"\n   [{i}] {category['name']}")
        
        # Get components in this category
        category_components = client.get_category_components(
            category_slug=category['slug']
        )
        
        component_count = len(category_components['components'])
        print(f"       Contains {component_count} component(s)")
        
        for comp in category_components['components'][:3]:
            print(f"         - {comp['part_name']} ({comp['manufacturer']})")
    
    print("\n" + "=" * 80)
    print("Workflow completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()