f APIf.inc ↗

"""
Founders, Inc. Portfolio API Client

A practical example of using the Parse API to interact with the Founders, Inc. portfolio.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional


class ParseClient:
    """Client for interacting with the Founders, Inc. Portfolio API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse API client.
        
        Args:
            api_key: API key for Parse. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "53c8d229-8d63-4c1e-bf9b-0b9f019b6458"
        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:
        """Make a request to the Parse API.
        
        Args:
            endpoint: The API endpoint to call.
            method: HTTP method (GET or POST).
            **params: Parameters to pass to the endpoint.
            
        Returns:
            The JSON response from the API.
        """
        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":
            payload = params if params else {}
            response = requests.post(url, headers=headers, json=payload)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")
        
        response.raise_for_status()
        return response.json()

    def get_portfolio(self) -> dict:
        """Get all portfolio companies from Founders, Inc.
        
        Returns:
            Dictionary containing total count and list of all companies.
        """
        return self._call("get_portfolio", method="GET")

    def search_portfolio(self, query: str) -> dict:
        """Search portfolio companies by keyword.
        
        Args:
            query: Search keyword to match against company name, tagline, 
                   description, industry, and domain.
        
        Returns:
            Dictionary containing total count and matching companies.
        """
        return self._call("search_portfolio", method="GET", query=query)

    def get_company(self, slug: str) -> dict:
        """Get detailed information about a specific company.
        
        Args:
            slug: URL slug of the company (e.g., 'zeit-medical', 'adaptyv-bio').
        
        Returns:
            Dictionary containing detailed company information.
        """
        return self._call("get_company", method="GET", slug=slug)


def extract_slug_from_url(url: str) -> str:
    """Extract the company slug from a portfolio URL.
    
    Args:
        url: The full portfolio URL.
    
    Returns:
        The company slug.
    """
    return url.split("/portfolio/")[-1].rstrip("/")


def main():
    """Practical workflow demonstrating the Founders, Inc. Portfolio API."""
    # Initialize the client
    client = ParseClient()
    
    print("=" * 80)
    print("FOUNDERS, INC. PORTFOLIO ANALYSIS")
    print("=" * 80)
    
    # Step 1: Search for AI/ML companies
    print("\n1. Searching for AI/ML related companies...")
    search_results = client.search_portfolio("AI")
    ai_companies = search_results.get("companies", [])
    print(f"   Found {len(ai_companies)} companies related to 'AI'")
    
    # Step 2: Analyze the top 3 AI companies
    print("\n2. Analyzing top 3 AI companies in detail...")
    for i, company in enumerate(ai_companies[:3], 1):
        print(f"\n   Company {i}: {company['name']}")
        print(f"   - Tagline: {company['tagline']}")
        print(f"   - Industry: {company['industry']}")
        print(f"   - Founded: {company['year_founded']}")
        print(f"   - Team Size: {company['team_size']}")
        print(f"   - Founders: {', '.join(company['founders'])}")
        print(f"   - Website: {company['domain']}")
        
        # Get full details for each company
        slug = extract_slug_from_url(company['url'])
        detailed_info = client.get_company(slug)
        print(f"   - Description: {detailed_info['description'][:100]}...")
    
    # Step 3: Search for companies in a specific industry/technology
    print("\n3. Searching for robotics companies...")
    robotics_results = client.search_portfolio("robotics")
    robotics_companies = robotics_results.get("companies", [])
    print(f"   Found {len(robotics_companies)} robotics-related companies:")
    
    for company in robotics_companies[:5]:  # Show top 5
        print(f"   - {company['name']} ({company['year_founded']}) - {company['tagline']}")
    
    # Step 4: Search for companies by founding year
    print("\n4. Searching for recently founded companies (2024-2025)...")
    recent_results = client.search_portfolio("2025")
    recent_companies = recent_results.get("companies", [])
    print(f"   Found {len(recent_companies)} companies founded in 2025:")
    
    for company in recent_companies[:5]:  # Show top 5
        print(f"   - {company['name']} - Team: {company['team_size']} people")
    
    # Step 5: Find companies with specific founders
    print("\n5. Searching for companies founded by specific individuals...")
    founder_results = client.search_portfolio("Ari")
    founder_companies = founder_results.get("companies", [])
    print(f"   Found {len(founder_companies)} companies with 'Ari' in their information:")
    
    for company in founder_companies[:3]:
        matching_founders = [f for f in company['founders'] if 'Ari' in f]
        if matching_founders:
            print(f"   - {company['name']}: {', '.join(matching_founders)}")
    
    # Step 6: Analyze industry distribution
    print("\n6. Analyzing company distribution across industries...")
    all_results = client.get_portfolio()
    all_companies = all_results.get("companies", [])
    
    industry_count = {}
    for company in all_companies:
        industry = company['industry']
        industry_count[industry] = industry_count.get(industry, 0) + 1
    
    print(f"   Total companies: {len(all_companies)}")
    print("   Top 10 industries by company count:")
    
    for industry, count in sorted(industry_count.items(), key=lambda x: x[1], reverse=True)[:10]:
        percentage = (count / len(all_companies)) * 100
        print(f"   - {industry}: {count} companies ({percentage:.1f}%)")
    
    # Step 7: Find largest teams
    print("\n7. Finding companies with the largest teams...")
    sorted_by_team = sorted(
        all_companies,
        key=lambda x: int(x.get('team_size', 0)),
        reverse=True
    )
    
    print("   Top 5 companies by team size:")
    for company in sorted_by_team[:5]:
        print(f"   - {company['name']}: {company['team_size']} people - {company['tagline']}")
    
    print("\n" + "=" * 80)
    print("Analysis complete!")
    print("=" * 80)


if __name__ == "__main__":
    main()