Python SDK

pip install canonical-search

from canonical_search import CanonicalClient

client = CanonicalClient(api_key="YOUR_API_KEY")
results = client.search("AI healthcare startups")

for company in results.results:
    print(f"{company.name} — {company.domain}")
    print(f"  {company.description[:100]}")

client = CanonicalClient(
    api_key="YOUR_API_KEY",
    base_url="https://trycanonical.ai",  # default
    timeout=30.0,                          # default
)

export CANONICAL_API_KEY=YOUR_API_KEY
export CANONICAL_API_BASE_URL=https://trycanonical.ai  # optional
export CANONICAL_TIMEOUT=30.0                          # optional

results = client.search(
    query="B2B SaaS companies",
    top_k=50,          # 1-1000, default 25
)

results = await client.asearch(
    query="B2B SaaS companies",
    top_k=50,
)

from canonical_search import CanonicalClient, StructuredFilters, StructuredLocation

client = CanonicalClient(api_key="YOUR_API_KEY")

results = client.search_structured(
    description="AI diagnostic platforms for hospitals",  # optional semantic core
    filters=StructuredFilters(
        location=StructuredLocation(countries=["United States"]),
        employee_count_min=50,
        employee_count_max=100,
        funding_series=["series_a", "series_b"],
        founding_year_min=2018,
    ),
    intent="sales_prospecting",  # optional ranking profile
    top_k=25,
)

results = client.find_similar_companies(
    company_domain="stripe.com",
    top_k=25,               # 1-1000, default 25
    intent="sales_timing",   # optional ranking profile
)

# async: await client.afind_similar_companies("stripe.com")

resp = client.lookup_companies(["stripe", "adyen"], k=5)

for name, result in resp.results.items():
    if result.auto_resolve_recommended:
        print(name, "→", result.primary_candidate_domain)
    else:
        # genuine toss-up — let the user pick from result.candidates
        print(name, "is ambiguous:", [c.domain for c in result.candidates])

# async: await client.alookup_companies([...])

details = client.get_company_details("stripe.com")

print(details.company.name, details.company.employee_count)
for person in details.people:
    print(person.name, "—", person.role)

# async: await client.aget_company_details("stripe.com")

status = client.get_account_status()
print(status.plan, status.credits.total, "credits left")
print(status.rate_limits.per_minute, "req/min")

# async: await client.aget_account_status()

class SearchResponse:
    results: list[Company]    # Matching companies
    count: int                # Number of results
    query: str                # Original query
    credits_used: int         # Credits consumed
    credits_remaining: int | None  # Remaining credits

class Company:
    name: str
    website: str
    domain: str                        # public handle — use for follow-up calls
    description: str
    headquarters: str | None
    employee_count: int | None
    founding_year: int | None
    dimensions: dict | None            # e.g. {"industry": ["Healthcare"]}
    funding: FundingSummary | None     # latest round, totals, investors

class FundingSummary:
    total_usd: float | None                  # equity rounds only
    round_count: int
    latest_date: str | None                  # ISO "YYYY-MM-DD"
    latest_amount_usd: float | None
    latest_series: str | None                # e.g. "series_b"
    latest_post_money_valuation: float | None
    latest_lead_investor: str | None
    all_investors: list[str]

class CompanyDetails:            # get_company_details(...)
    company: CompanyProfile | None    # full profile (name, hq, funding, dimensions, defunct)
    people: list[Person]              # founders + execs (may be empty)
    leadership_data: str | None       # "available" | "not_available" | "error"
    relationships: Relationships | None  # corporate family (present when edges exist)
    credits_used: int | None
    credits_remaining: int | None

class Person:
    name: str
    role: str                         # e.g. "ceo", "cofounder"
    role_secondary: str | None
    headline: str | None
    linkedin_url: str | None
    prior_companies: list[PriorCompany]

class LookupResponse:             # lookup_companies(...)
    results: dict[str, LookupResult]  # keyed by each input name
    credits_used: int
    credits_remaining: int | None

class LookupResult:
    confidence: str                   # "high" | "medium" | "low"
    auto_resolve_recommended: bool    # True = safe to use primary; False = ask the user
    primary_candidate_domain: str | None
    candidates: list[LookupCandidate] # each has name, domain, headquarters, description

class AccountStatus:              # get_account_status()
    credits: Credits                  # .total / .subscription / .extra / .subscription_resets_at
    plan: str | None                  # "free" | "starter" | "pro"
    rate_limits: RateLimits           # .per_minute / .per_day
    billing_url: str

from canonical_search import (
    CanonicalClient,
    AuthenticationError,
    InsufficientCreditsError,
    NotFoundError,
    InvalidRequestError,
    RateLimitError,
    APIError,
)

client = CanonicalClient(api_key="YOUR_API_KEY")

try:
    results = client.search("fintech")
except AuthenticationError:
    print("Invalid or missing API key")
except InsufficientCreditsError:
    print("Out of credits — top up at /billing")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except APIError as e:
    print(f"API error: {e}")