# sec-company-lookup
[](https://github.com/JNewman-cell/sec-company-lookup/actions/workflows/tests.yml)
[](https://opensource.org/licenses/MIT)
Fast, cached SEC company lookups by ticker, CIK, or company name with automatic data updates and multi-level caching.
## Installation
```bash
pip install sec-company-lookup
```
## Quick Start
```python
from sec_company_lookup import set_user_email, get_company
# Configure email for SEC API compliance (required)
set_user_email("your@email.com")
# Smart lookup - auto-detects ticker, CIK, or company name
companies = get_company("AAPL") # By ticker
companies = get_company(320193) # By CIK
companies = get_company("Apple") # By name (fuzzy)
print(companies)
# [{'cik': 320193, 'ticker': 'AAPL', 'name': 'Apple Inc.'}]
```
## Core Features
- **Smart lookup** - Auto-detects ticker, CIK, or company name
- **Fast caching** - Multi-tier caching (memory + SQLite + LRU)
- **Fuzzy search** - Find companies with partial names
- **Batch operations** - Process multiple lookups efficiently
- **Auto-updates** - Downloads latest SEC data when needed
## Email Configuration
The SEC requires contact information. Configure using any method:
```python
# Method 1: In code (recommended)
from sec_company_lookup import set_user_email
set_user_email("your@email.com")
# Method 2: Environment variable
# export SECCOMPANYLOOKUP_USER_EMAIL="your@email.com"
```
## API Functions
### Core Lookup Functions
```python
from sec_company_lookup import (
get_company, # Smart lookup (auto-detects input type)
get_companies_by_tickers, # Lookup by ticker(s) - single or batch
get_companies_by_ciks, # Lookup by CIK(s) - single or batch
get_companies_by_names, # Lookup by name(s) - single or batch
)
# Single lookups
company = get_company("AAPL") # Auto-detect (returns list)
company = get_companies_by_tickers("MSFT") # By ticker (returns CompanyData or None)
companies = get_companies_by_ciks(789019) # By CIK (returns list)
company = get_companies_by_names("Apple", fuzzy=True) # By name (returns CompanyData or None)
# Batch lookups
results = get_companies_by_tickers(["AAPL", "MSFT"]) # Returns dict with structured responses
results = get_companies_by_ciks([320193, 789019]) # Returns dict mapping CIK to list
results = get_companies_by_names(["Apple", "Microsoft"]) # Returns dict with structured responses
```
### Search Functions
```python
from sec_company_lookup import (
search_companies, # General search across all fields
search_companies_by_company_name, # Company name specific search
)
# Examples
results = search_companies("tech", limit=10)
results = search_companies_by_company_name("Apple", fuzzy=True, limit=5)
```
### Batch Operations
```python
from sec_company_lookup import (
get_companies_by_tickers, # Batch ticker lookup
get_companies_by_ciks, # Batch CIK lookup
get_companies_by_names, # Batch name lookup
)
# Batch ticker lookup
tickers = ["AAPL", "MSFT", "GOOGL"]
results = get_companies_by_tickers(tickers)
# Returns: {
# "AAPL": {"success": True, "data": {...}},
# "MSFT": {"success": True, "data": {...}},
# "GOOGL": {"success": True, "data": {...}}
# }
# Batch CIK lookup (CIKs can map to multiple companies)
ciks = [320193, 789019, 1652044]
results = get_companies_by_ciks(ciks)
# Returns: {
# 320193: {"success": True, "data": [...]},
# 789019: {"success": True, "data": [...]},
# 1652044: {"success": True, "data": [...]}
# }
# Batch name lookup
names = ["Apple Inc.", "Microsoft Corporation"]
results = get_companies_by_names(names, fuzzy=True)
# Returns: {
# "Apple Inc.": {"success": True, "data": {...}},
# "Microsoft Corporation": {"success": True, "data": {...}}
# }
```
### Cache Management
```python
from sec_company_lookup import update_data, clear_cache, get_cache_info
# Force update from SEC
update_data()
# Check cache status
info = get_cache_info()
print(f"Companies cached: {info['companies_cached']}")
print(f"Cache age: {info['cache_age_hours']:.1f} hours")
# Clear all caches
clear_cache()
```
## Data Structure
Each company record contains:
```python
{
'cik': 320193, # SEC Central Index Key (integer)
'ticker': 'AAPL', # Stock ticker symbol
'name': 'Apple Inc.' # Official company name
}
```
## Performance
Multi-tier caching provides fast lookups:
- **Memory cache**: < 1ms
- **Database lookup**: 1-5ms
- **Initial download**: ~2 seconds
## Package Structure
```
sec_company_lookup/
├── __init__.py # Main package entry point
├── sec_company_lookup.py # Core backend implementation
├── config.py # Email configuration
├── api/
│ ├── __init__.py
│ └── api.py # Public API layer
├── db/
│ ├── __init__.py
│ └── db.py # SQLite database operations
├── types/
│ ├── __init__.py
│ └── types.py # Type definitions
└── utils/
├── __init__.py
└── utils.py # Utility functions & data fetching
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "sec-company-lookup",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "SEC, CIK, ticker, finance, company, lookup, cache, edgar",
"author": null,
"author_email": "Jackson Newman <jpnewman167@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c9/96/964f263b813b78ef7e56ff224e18b44aa0447f49942f9a4f87f08e51b78c/sec_company_lookup-0.1.0.tar.gz",
"platform": null,
"description": "# sec-company-lookup\r\n\r\n[](https://github.com/JNewman-cell/sec-company-lookup/actions/workflows/tests.yml)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nFast, cached SEC company lookups by ticker, CIK, or company name with automatic data updates and multi-level caching.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install sec-company-lookup\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nfrom sec_company_lookup import set_user_email, get_company\r\n\r\n# Configure email for SEC API compliance (required)\r\nset_user_email(\"your@email.com\")\r\n\r\n# Smart lookup - auto-detects ticker, CIK, or company name\r\ncompanies = get_company(\"AAPL\") # By ticker\r\ncompanies = get_company(320193) # By CIK\r\ncompanies = get_company(\"Apple\") # By name (fuzzy)\r\n\r\nprint(companies)\r\n# [{'cik': 320193, 'ticker': 'AAPL', 'name': 'Apple Inc.'}]\r\n```\r\n\r\n## Core Features\r\n\r\n- **Smart lookup** - Auto-detects ticker, CIK, or company name\r\n- **Fast caching** - Multi-tier caching (memory + SQLite + LRU)\r\n- **Fuzzy search** - Find companies with partial names\r\n- **Batch operations** - Process multiple lookups efficiently\r\n- **Auto-updates** - Downloads latest SEC data when needed\r\n\r\n## Email Configuration\r\n\r\nThe SEC requires contact information. Configure using any method:\r\n\r\n```python\r\n# Method 1: In code (recommended)\r\nfrom sec_company_lookup import set_user_email\r\nset_user_email(\"your@email.com\")\r\n\r\n# Method 2: Environment variable\r\n# export SECCOMPANYLOOKUP_USER_EMAIL=\"your@email.com\"\r\n```\r\n\r\n## API Functions\r\n\r\n### Core Lookup Functions\r\n\r\n```python\r\nfrom sec_company_lookup import (\r\n get_company, # Smart lookup (auto-detects input type)\r\n get_companies_by_tickers, # Lookup by ticker(s) - single or batch\r\n get_companies_by_ciks, # Lookup by CIK(s) - single or batch\r\n get_companies_by_names, # Lookup by name(s) - single or batch\r\n)\r\n\r\n# Single lookups\r\ncompany = get_company(\"AAPL\") # Auto-detect (returns list)\r\ncompany = get_companies_by_tickers(\"MSFT\") # By ticker (returns CompanyData or None)\r\ncompanies = get_companies_by_ciks(789019) # By CIK (returns list)\r\ncompany = get_companies_by_names(\"Apple\", fuzzy=True) # By name (returns CompanyData or None)\r\n\r\n# Batch lookups\r\nresults = get_companies_by_tickers([\"AAPL\", \"MSFT\"]) # Returns dict with structured responses\r\nresults = get_companies_by_ciks([320193, 789019]) # Returns dict mapping CIK to list\r\nresults = get_companies_by_names([\"Apple\", \"Microsoft\"]) # Returns dict with structured responses\r\n```\r\n\r\n### Search Functions\r\n\r\n```python\r\nfrom sec_company_lookup import (\r\n search_companies, # General search across all fields\r\n search_companies_by_company_name, # Company name specific search\r\n)\r\n\r\n# Examples \r\nresults = search_companies(\"tech\", limit=10)\r\nresults = search_companies_by_company_name(\"Apple\", fuzzy=True, limit=5)\r\n```\r\n\r\n### Batch Operations\r\n\r\n```python\r\nfrom sec_company_lookup import (\r\n get_companies_by_tickers, # Batch ticker lookup\r\n get_companies_by_ciks, # Batch CIK lookup\r\n get_companies_by_names, # Batch name lookup\r\n)\r\n\r\n# Batch ticker lookup\r\ntickers = [\"AAPL\", \"MSFT\", \"GOOGL\"]\r\nresults = get_companies_by_tickers(tickers)\r\n# Returns: {\r\n# \"AAPL\": {\"success\": True, \"data\": {...}},\r\n# \"MSFT\": {\"success\": True, \"data\": {...}},\r\n# \"GOOGL\": {\"success\": True, \"data\": {...}}\r\n# }\r\n\r\n# Batch CIK lookup (CIKs can map to multiple companies)\r\nciks = [320193, 789019, 1652044]\r\nresults = get_companies_by_ciks(ciks)\r\n# Returns: {\r\n# 320193: {\"success\": True, \"data\": [...]},\r\n# 789019: {\"success\": True, \"data\": [...]},\r\n# 1652044: {\"success\": True, \"data\": [...]}\r\n# }\r\n\r\n# Batch name lookup\r\nnames = [\"Apple Inc.\", \"Microsoft Corporation\"]\r\nresults = get_companies_by_names(names, fuzzy=True)\r\n# Returns: {\r\n# \"Apple Inc.\": {\"success\": True, \"data\": {...}},\r\n# \"Microsoft Corporation\": {\"success\": True, \"data\": {...}}\r\n# }\r\n```\r\n\r\n### Cache Management\r\n\r\n```python\r\nfrom sec_company_lookup import update_data, clear_cache, get_cache_info\r\n\r\n# Force update from SEC\r\nupdate_data()\r\n\r\n# Check cache status\r\ninfo = get_cache_info()\r\nprint(f\"Companies cached: {info['companies_cached']}\")\r\nprint(f\"Cache age: {info['cache_age_hours']:.1f} hours\")\r\n\r\n# Clear all caches\r\nclear_cache()\r\n```\r\n\r\n## Data Structure\r\n\r\nEach company record contains:\r\n\r\n```python\r\n{\r\n 'cik': 320193, # SEC Central Index Key (integer)\r\n 'ticker': 'AAPL', # Stock ticker symbol \r\n 'name': 'Apple Inc.' # Official company name\r\n}\r\n```\r\n\r\n## Performance\r\n\r\nMulti-tier caching provides fast lookups:\r\n\r\n- **Memory cache**: < 1ms\r\n- **Database lookup**: 1-5ms \r\n- **Initial download**: ~2 seconds\r\n\r\n## Package Structure\r\n\r\n```\r\nsec_company_lookup/\r\n\u251c\u2500\u2500 __init__.py # Main package entry point\r\n\u251c\u2500\u2500 sec_company_lookup.py # Core backend implementation\r\n\u251c\u2500\u2500 config.py # Email configuration\r\n\u251c\u2500\u2500 api/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 api.py # Public API layer\r\n\u251c\u2500\u2500 db/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 db.py # SQLite database operations\r\n\u251c\u2500\u2500 types/\r\n\u2502 \u251c\u2500\u2500 __init__.py\r\n\u2502 \u2514\u2500\u2500 types.py # Type definitions\r\n\u2514\u2500\u2500 utils/\r\n \u251c\u2500\u2500 __init__.py\r\n \u2514\u2500\u2500 utils.py # Utility functions & data fetching\r\n```\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Fast, cached SEC company data lookups by ticker, CIK, or company name",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/JNewman-cell/sec-company-lookup",
"Issues": "https://github.com/JNewman-cell/sec-company-lookup/issues",
"Repository": "https://github.com/JNewman-cell/sec-company-lookup"
},
"split_keywords": [
"sec",
" cik",
" ticker",
" finance",
" company",
" lookup",
" cache",
" edgar"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7dee3d1d90c85cffd588c3c07c6b2a62b26f42ab845d0568c08ff79cb2bd33a8",
"md5": "1b08bd27f8e573bfb26ed3fa5ec7e20b",
"sha256": "ef09a63a2d3ced2b199d829664d3e31dd242bb087e6f07f35a7082898ef4d887"
},
"downloads": -1,
"filename": "sec_company_lookup-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b08bd27f8e573bfb26ed3fa5ec7e20b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22890,
"upload_time": "2025-10-30T22:14:50",
"upload_time_iso_8601": "2025-10-30T22:14:50.709262Z",
"url": "https://files.pythonhosted.org/packages/7d/ee/3d1d90c85cffd588c3c07c6b2a62b26f42ab845d0568c08ff79cb2bd33a8/sec_company_lookup-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c996964f263b813b78ef7e56ff224e18b44aa0447f49942f9a4f87f08e51b78c",
"md5": "1a95d910bea73499900cb696c4c6b9fa",
"sha256": "04e15dc4ac913969a4f3dd4b6051f23f1c641058b616b122805a8f423ce42a6a"
},
"downloads": -1,
"filename": "sec_company_lookup-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1a95d910bea73499900cb696c4c6b9fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 38857,
"upload_time": "2025-10-30T22:14:53",
"upload_time_iso_8601": "2025-10-30T22:14:53.167300Z",
"url": "https://files.pythonhosted.org/packages/c9/96/964f263b813b78ef7e56ff224e18b44aa0447f49942f9a4f87f08e51b78c/sec_company_lookup-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 22:14:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JNewman-cell",
"github_project": "sec-company-lookup",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "types-requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "sec-company-lookup"
}
JSON
