Security News
The Changelog Podcast: Practical Steps to Stay Safe on npm
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.
By Sarah Gooding - Oct 31, 2025
🚀 DAY 5 OF LAUNCH WEEK: Introducing Socket Firewall Enterprise.Learn more →
thecompaniesapi
Advanced tools
- Version
- 1.0.2
- Maintainers
- 1
The Companies API SDK for Python
A fully-featured Python SDK for The Companies API, providing type-safe access to company data, locations, industries, technologies, job titles, lists, and more.
If you need more details about a specific endpoint, you can find the corresponding documentation in the API reference.
You can also contact us on our livechat if you have any questions.
🚀 Features
- Expose all our 30+ endpoints and gives access to 50M+ companies from your codebase
- Type-safe API client with full access to our OpenAPI schemas
- Real-time company enrichment with both synchronous and asynchronous options
- Powerful search capabilities with filters, sorting and pagination
- Create and manage your company lists
- Track and monitor enrichment actions and requests
- Generate detailed analytics and insights for searches and lists
- Natural language querying for structured company information
- Lightweight with minimal dependencies
📦 Installation
pip install thecompaniesapi
That's it! The SDK includes pre-generated types and works immediately after installation.
🔑 Initialize the client
Get your API token from your settings page and initialize our client with Client.
The API token is required to authenticate your requests and should be kept secure. Never commit your API token to version control or share it publicly.
from thecompaniesapi import Client
tca = Client(api_token='your-api-token')
🏬 Companies
Search companies
🕹️ Use case: How to build a company search engine with our API
🔍 To learn more about our query system, please read our documentation.
# Search companies by industry and size
response = tca.search_companies(
query=[
{"attribute": "about.industries", "operator": "or", "sign": "equals", "values": ["computer-software"]},
{"attribute": "about.totalEmployees", "operator": "or", "sign": "equals", "values": ["10-50"]}
],
size=25
)
companies = response["data"]["companies"] # Companies that match the query
meta = response["data"]["meta"] # Meta information
Search companies by name
🕹️ Use case: Add a company search with autocomplete to your application
response = tca.search_companies_by_name(
name="The Companies API",
size=2
)
companies = response["data"]["companies"] # Companies that match the name
meta = response["data"]["meta"] # Meta information
Search companies using a prompt
# Search 25 companies for a specific prompt
response = tca.search_companies_by_prompt(
prompt="SaaS Companies in the United States with more than 100 employees",
size=25
)
companies = response["data"]["companies"] # Companies that match the prompt
meta = response["data"]["meta"] # Meta information
Search similar companies
# Search 25 companies that are similar to Crisp and Intercom
response = tca.search_similar_companies(
domains=["crisp.chat", "intercom.com"],
size=25
)
companies = response["data"]["companies"] # Companies that are similar to the domains
meta = response["data"]["meta"] # Meta information
Count companies matching your query
# Count how many companies are in the computer-software industry
response = tca.count_companies(
query=[
{
"attribute": "about.industries",
"operator": "or",
"sign": "equals",
"values": ["computer-software"]
}
]
)
count = response["data"] # Number of companies that match the query
Enrich a company from a domain name
# Fetch company data from our database without enrichment (faster response)
response = tca.fetch_company(domain="microsoft.com")
company = response["data"] # The company profile
# Fetch company data and re-analyze it in real-time to get fresh, up-to-date information (slower but more accurate)
response = tca.fetch_company(
domain="microsoft.com",
refresh=True
)
company = response["data"] # The company profile
Enrich a company from an email
🕹️ Use case: Enrich your users at signup with the latest information about their company
# Fetch the company profile behind a professional email address
response = tca.fetch_company_by_email(email="jack@openai.com")
company = response["data"] # The company profile
Enrich a company from a social network URL
# Fetch the company profile behind a social network URL
response = tca.fetch_company_by_social(
linkedin="https://www.linkedin.com/company/apple"
)
company = response["data"] # The company profile
Find a company email patterns
# Fetch the company email patterns for a specific domain
response = tca.fetch_company_email_patterns(domain="apple.com")
patterns = response["data"] # The company email patterns
Ask a question about a company
# Ask what products a company offers using its domain
response = tca.ask_company(
domain="microsoft.com",
question="What products does this company offer?",
model="large", # 'small' is also available
fields=[
{
"key": "products",
"type": "array|string",
"description": "The products that the company offers"
}
]
)
answer = response["data"]["answer"] # Structured AI response
meta = response["data"]["meta"] # Meta information
Fetch the context of a company
# Get AI-generated strategic insights about a company
response = tca.fetch_company_context(domain="microsoft.com")
context = response["data"]["context"] # Includes market, model, differentiators, etc.
meta = response["data"]["meta"] # Meta information
Fetch analytics data for a query or your lists
# Analyze company distribution by business type
response = tca.fetch_companies_analytics(
attribute="about.businessType",
query=[
{
"attribute": "locations.headquarters.country.code",
"operator": "or",
"sign": "equals",
"values": ["us", "gb", "fr"]
}
]
)
analytics = response["data"]["data"] # Aggregated values
meta = response["data"]["meta"] # Meta information
Export analytics data in multiple formats for a search
# Export analytics to CSV
response = tca.export_companies_analytics(
format="csv",
attributes=["about.industries", "about.totalEmployees"],
query=[
{
"attribute": "technologies.active",
"operator": "or",
"sign": "equals",
"values": ["shopify"]
}
]
)
analytics = response["data"]["data"] # Aggregated values
meta = response["data"]["meta"] # Meta information
🎯 Actions
Request an action on one or more companies
# Request an enrichment job on multiple companies
response = tca.request_action(
domains=["microsoft.com", "apple.com"],
job="enrich-companies",
estimate=False
)
actions = response["data"]["actions"] # Track this via fetch_actions
meta = response["data"]["meta"] # Meta information
Fetch the actions for your actions
# Fetch recent actions
response = tca.fetch_actions(
status="completed",
page=1,
size=5
)
actions = response["data"]["actions"] # Actions that match the query
meta = response["data"]["meta"] # Meta information
🏭 Industries
Search industries
# Search industries by keyword
response = tca.search_industries(
search="software",
size=10
)
industries = response["data"]["industries"] # Industries that match the keyword
meta = response["data"]["meta"] # Meta information
Find similar industries
# Find industries similar to given ones
response = tca.search_industries_similar(
industries=["saas", "fintech"]
)
similar = response["data"]["industries"] # Industries that are similar to the given ones
meta = response["data"]["meta"] # Meta information
⚛️ Technologies
Search technologies
# Search technologies by keyword
response = tca.search_technologies(
search="shopify",
size=10
)
technologies = response["data"]["technologies"] # Technologies that match the keyword
meta = response["data"]["meta"] # Meta information
🌍 Locations
Search cities
# Search cities by name
response = tca.search_cities(
search="new york",
size=5
)
cities = response["data"]["cities"] # Cities that match the name
meta = response["data"]["meta"] # Meta information
Search counties
# Search counties by name
response = tca.search_counties(
search="orange",
size=5
)
counties = response["data"]["counties"] # Counties that match the name
meta = response["data"]["meta"] # Meta information
Search states
# Search states by name
response = tca.search_states(
search="california",
size=5
)
states = response["data"]["states"] # States that match the name
meta = response["data"]["meta"] # Meta information
Search countries
# Search countries by name
response = tca.search_countries(
search="france",
size=5
)
countries = response["data"]["countries"] # Countries that match the name
meta = response["data"]["meta"] # Meta information
Search continents
# Search continents by name
response = tca.search_continents(
search="asia",
size=5
)
continents = response["data"]["continents"] # Continents that match the name
meta = response["data"]["meta"] # Meta information
💼 Job titles
Enrich a job title from its name
# Enrich "chief marketing officer"
response = tca.enrich_job_titles(name="chief marketing officer")
job_title = response["data"] # Contains department, seniority, etc.
📋 Lists
Fetch your lists
# Fetch your lists
response = tca.fetch_lists()
lists = response["data"]["lists"] # Lists that match the query
meta = response["data"]["meta"] # Meta information
Create a list of companies
# Create a list of companies
response = tca.create_list(
name="My SaaS List",
type="companies"
)
new_list = response["data"] # The new list
Fetch companies in your list
# Fetch companies in a list
response = tca.fetch_companies_in_list(list_id=1234)
companies = response["data"]["companies"] # Companies that match the list
meta = response["data"]["meta"] # Meta information
Add or remove companies in your list
# Add companies to a list
response = tca.toggle_companies_in_list(
list_id=1234,
companies=["apple.com", "stripe.com"]
)
list_data = response["data"] # The updated list
👥 Teams
Fetch your team
# Fetch your team details
response = tca.fetch_team()
team = response["data"] # Your team details
🔧 Utilities
Fetch the health of the API
# Check API health status
response = tca.fetch_api_health()
health = response["data"] # The health of the API
Fetch the OpenAPI schema
# Fetch OpenAPI schema
response = tca.fetch_openapi()
schema = response["data"] # The OpenAPI schema
🧪 Testing
Unit Tests
Run the unit tests that don't require an API token:
pytest tests/test_client.py -m unit
Integration Tests
The SDK includes comprehensive integration tests that make real API calls. To run them:
-
Create a
.envfile in the project root:# Required: Your API token from https://www.thecompaniesapi.com/settings/api-tokens TCA_API_TOKEN=your-api-token-here # Optional configurations TCA_API_URL=https://api.thecompaniesapi.com TCA_VISITOR_ID=your-visitor-id TCA_TIMEOUT=30 -
Install test dependencies:
pip install -e ".[test]" -
Run integration tests:
# Run all integration tests pytest tests/test_integration.py -m integration -v # Run all tests except integration tests pytest -m "not integration" # Run all tests (unit + integration) pytest
The integration tests cover:
- Company search (GET and POST methods)
- Company counting and filtering
- Company lookup by email and domain
- Complex query serialization
- Error handling and edge cases
- Dynamic method access
- API health checks
🔗 Links
📄 License
MIT License © TheCompaniesAPI
FAQs
Python SDK for The Companies API
We found that thecompaniesapi demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Security News
Security Community Slams MIT-linked Report Claiming AI Powers 80% of Ransomware
Experts push back on new claims about AI-driven ransomware, warning that hype and sponsored research are distorting how the threat is understood.
By Sarah Gooding - Oct 30, 2025
Security News
Ruby Core Team Assumes Stewardship of RubyGems and Bundler, Former Maintainers Offer to Transfer All Rights to Matz
Ruby's creator Matz assumes control of RubyGems and Bundler repositories while former maintainers agree to step back and transfer all rights to end the dispute.
By Sarah Gooding - Oct 29, 2025