ventureradar-api-example.py

"""
VentureRadar Company Discovery API: A Quick Start Example
See more at: https://apify.com/johnvc/ventureradar-company-api?fpr=9n7kx3
Input schema: https://apify.com/johnvc/ventureradar-company-api/input-schema?fpr=9n7kx3

This script shows how to call the VentureRadar Company Discovery API on Apify from
Python and read its structured JSON output. It sends one or more company profile
URLs and prints the fields that matter for startup database work: sector focus,
founding year, scores, milestones, and the funding signals that say which
accelerators, incubators, grants, or awards are behind a company.

The Actor bills per company profile returned, so the default run collects exactly
one company. Pass --url one or more times to collect your own list.

Get your free Apify API key at: https://apify.com?fpr=9n7kx3

Examples:
  uv run python ventureradar-api-example.py
  uv run python ventureradar-api-example.py --url "https://www.ventureradar.com/organisation/Theneo/b40ae154-6867-456f-a215-d98fdae0048c"
  uv run python ventureradar-api-example.py --json
"""

from __future__ import annotations

import argparse
import json
import os
from typing import Any

from apify_client import ApifyClient
from dotenv import load_dotenv

load_dotenv()

ACTOR_ID = "johnvc/ventureradar-company-api"

# A company profile URL carries BOTH the company name and the profile id.
# There is no shorthand form: a bare company name cannot be resolved.
DEFAULT_COMPANY_URLS = [
    "https://www.ventureradar.com/organisation/Theneo/b40ae154-6867-456f-a215-d98fdae0048c",
]


def print_company(item: dict[str, Any]) -> None:
    """Pull the useful fields out of one company row and print them.

    Fields with no value on the source profile are left out of the row entirely,
    so every read below uses .get() and tolerates a thin profile.

    Args:
        item: One dataset row where result_type is "company".
    """
    name = item.get("companyName", "(unnamed)")
    founded = item.get("founded")
    where = item.get("location") or item.get("country")
    header = name
    if where and founded:
        header += f" ({where}, founded {founded})"
    elif where:
        header += f" ({where})"
    elif founded:
        header += f" (founded {founded})"
    print(header)

    if item.get("website"):
        print(f"  Website:    {item['website']}")
    if item.get("ownership"):
        print(f"  Ownership:  {item['ownership']}")

    focus = item.get("areasOfFocus") or item.get("keywords") or []
    if focus:
        print(f"  Focus:      {', '.join(focus)}")

    # Headline score plus the sub-scores behind it.
    if item.get("analystScore") is not None:
        print(f"  Analyst:    {item['analystScore']}")
    scores = item.get("scores") or {}
    if scores:
        parts = [f"{key}={value}" for key, value in scores.items()]
        print(f"  Scores:     {', '.join(parts)}")
    if item.get("websitePopularity"):
        print(f"  Popularity: {item['websitePopularity']}")

    # Funding signals are the differentiated field: who backed this company,
    # with a source link for each entry. They are provenance, not amounts.
    signals = item.get("fundingSignals") or []
    if signals:
        print(f"  Funding signals ({len(signals)}):")
        for signal in signals:
            category = signal.get("category", "signal")
            source = signal.get("source", "")
            print(f"    - [{category}] {source}")
            if signal.get("url"):
                print(f"      {signal['url']}")
    else:
        print("  Funding signals: none on record")

    milestones = item.get("milestones") or []
    if milestones:
        print(f"  Milestones ({len(milestones)}):")
        for milestone in milestones:
            print(f"    - {milestone.get('date', '')}: {milestone.get('text', '')}")

    similar = item.get("similarCompanies") or []
    if similar:
        print(f"  Similar:    {', '.join(similar)}")

    if item.get("linkedin"):
        print(f"  LinkedIn:   {item['linkedin']}")
    if item.get("twitter"):
        print(f"  X:          {item['twitter']}")

    if item.get("summary"):
        print(f"  Summary:    {item['summary']}")
    print()


def print_error(item: dict[str, Any]) -> None:
    """Print one error row so a failed input never disappears silently."""
    print(f"ERROR for {item.get('sourceUrl', '(unknown URL)')}")
    print(f"  {item.get('error_type', 'Error')}: {item.get('error_message', '')}")
    print()


def run_default(client: ApifyClient, company_urls: list[str], as_json: bool) -> None:
    """Collect the given company profiles and print the results.

    Args:
        client: An authenticated Apify client.
        company_urls: Company profile URLs to collect.
        as_json: Print raw JSON rows instead of the formatted summary.
    """
    # The list is kept to a single company by default to keep this first run
    # inexpensive: billing is one event per company profile returned. Add more
    # URLs with --url once you have your own API key and know your budget.
    # The Actor accepts up to 1000 profile URLs in one run.
    run_input: dict[str, Any] = {
        "companyUrls": company_urls,
    }

    print(f"Collecting {len(company_urls)} company profile(s) ...\n")
    run = client.actor(ACTOR_ID).call(run_input=run_input)
    if run is None:
        raise SystemExit("The Actor run did not return a result.")

    # apify-client 3.x returns a typed Run object, so read the attribute.
    items = list(client.dataset(run.default_dataset_id).iterate_items())
    print(f"Returned {len(items)} row(s) from run {run.id}.\n")

    if as_json:
        print(json.dumps(items, indent=2, ensure_ascii=False, default=str))
        return

    companies = [row for row in items if row.get("result_type") == "company"]
    errors = [row for row in items if row.get("result_type") == "error"]

    for row in companies:
        print_company(row)
    for row in errors:
        print_error(row)

    # A quick deal-sourcing filter: which of these have accelerator or
    # incubator provenance on record?
    backed = [row for row in companies if row.get("fundingSignals")]
    print(f"{len(backed)} of {len(companies)} company row(s) carry at least one funding signal.")


def main() -> None:
    """Parse arguments and run the quick start."""
    parser = argparse.ArgumentParser(
        description="VentureRadar Company Discovery API example",
    )
    parser.add_argument(
        "--url",
        dest="urls",
        action="append",
        default=None,
        help=(
            "A company profile URL to collect. Repeat for several companies. "
            "The URL must contain both the company name and the profile id."
        ),
    )
    parser.add_argument(
        "--json",
        dest="as_json",
        action="store_true",
        help="Print the raw JSON rows instead of the formatted summary.",
    )
    args = parser.parse_args()

    token = os.getenv("APIFY_API_TOKEN")
    if not token:
        raise SystemExit(
            "Set APIFY_API_TOKEN in .env or the environment. "
            "Get a free key at https://apify.com?fpr=9n7kx3"
        )

    client = ApifyClient(token)
    run_default(client, args.urls or DEFAULT_COMPANY_URLS, args.as_json)


if __name__ == "__main__":
    main()