# CUFinder Python SDK
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/cufinder-py)
Type-safe Python SDK for easily integrating with the CUFinder B2B Data Enrichment API.
## Features
- 🚀 **Type-safe**: Built with Pydantic for full type safety and validation
- 🔧 **Easy to use**: Simple, intuitive API design
- 🛡️ **Robust**: Comprehensive error handling and retry logic
- 📚 **Well documented**: Extensive documentation and examples
- 🔄 **Async ready**: Built for both sync and async usage patterns
- 🎯 **Production ready**: Battle-tested in production environments
## Installation
```bash
pip install cufinder-py
```
## Quick Start
```python
from cufinder import CufinderSDK
# Initialize the SDK
sdk = CufinderSDK(api_key="your-api-key-here")
# Get company domain from company name
company = sdk.cuf(
company_name="TechCorp",
country_code="US"
)
print(company.domain) # 'techcorp.com'
# Enrich LinkedIn profile
profile = sdk.epp(
linkedin_url="https://linkedin.com/in/johndoe"
)
print(profile.person.full_name) # 'John Doe'
# Search local businesses
businesses = sdk.lbs(
name="coffee shop",
city="San Francisco",
state="CA"
)
print(f"Found {businesses.total} businesses")
```
## API Services
### CUF - Company URL Finder
Find the official website URL of a company based on its name.
```python
domain = sdk.cuf(
company_name="Microsoft",
country_code="US"
)
```
### EPP - Email Pattern Predictor
Enrich LinkedIn profiles to get person and company data.
```python
profile = sdk.epp(
linkedin_url="https://linkedin.com/in/satyanadella"
)
```
### LBS - Local Business Search
Search for local businesses by location, industry, or name.
```python
businesses = sdk.lbs(
name="restaurant",
city="New York",
state="NY",
industry="food"
)
```
## Configuration
```python
sdk = CufinderSDK(
api_key="your-api-key",
base_url="https://api.cufinder.io/v2", # Optional
timeout=30, # Optional, default 30 seconds
max_retries=3 # Optional, default 3 retries
)
```
## Error Handling
The SDK provides comprehensive error handling with specific exception types:
```python
from cufinder import (
CufinderError,
AuthenticationError,
ValidationError,
RateLimitError,
CreditLimitError,
NetworkError
)
try:
result = sdk.cuf(company_name="TechCorp", country_code="US")
except ValidationError as e:
print(f"Validation error: {e}")
except AuthenticationError as e:
print(f"Authentication failed: {e}")
except RateLimitError as e:
print(f"Rate limit exceeded. Retry after: {e.retry_after} seconds")
except CreditLimitError as e:
print(f"Credit limit exceeded: {e}")
except NetworkError as e:
print(f"Network error: {e}")
except CufinderError as e:
print(f"API error: {e}")
```
## Advanced Usage
### Direct Client Access
For advanced usage, you can access the underlying HTTP client:
```python
client = sdk.get_client()
# Make custom requests
response = client.get("/custom-endpoint", params={"param": "value"})
```
### Custom Headers
```python
response = client.post(
"/endpoint",
data={"key": "value"},
headers={"Custom-Header": "value"}
)
```
## Response Models
All responses are strongly typed using Pydantic models:
```python
from cufinder.models import CufResponse, EppResponse, LbsResponse
# CUF Response
domain: CufResponse = sdk.cuf("TechCorp", "US")
print(domain.domain)
print(domain.confidence)
# EPP Response
profile: EppResponse = sdk.epp("https://linkedin.com/in/johndoe")
print(profile.person.full_name)
print(profile.company.name)
# LBS Response
businesses: LbsResponse = sdk.lbs(city="San Francisco")
print(businesses.total)
print(businesses.businesses[0]["name"])
```
## Development
### Setup
```bash
git clone https://github.com/CUFinder/cufinder-py.git
cd cufinder-py
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black src/ tests/
isort src/ tests/
```
### Type Checking
```bash
mypy src/
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- 📧 Email: support@cufinder.io
- 📖 Documentation: [https://docs.cufinder.io/python](https://docs.cufinder.io/python)
- 🐛 Issues: [https://github.com/CUFinder/cufinder-py/issues](https://github.com/CUFinder/cufinder-py/issues)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
Raw data
{
"_id": null,
"home_page": "https://github.com/CUFinder/cufinder-py",
"name": "cufinder-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "CUFinder, api, sdk, python, b2b, data-enrichment",
"author": "Cufinder Team",
"author_email": "CUFinder Team <support@cufinder.io>",
"download_url": "https://files.pythonhosted.org/packages/a2/67/69efaab9e61f36058b76e27bcce16d69cba496500e3b7fc13284500ff99d/cufinder_py-0.1.0.tar.gz",
"platform": null,
"description": "# CUFinder Python SDK\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/cufinder-py)\n\nType-safe Python SDK for easily integrating with the CUFinder B2B Data Enrichment API.\n\n## Features\n\n- \ud83d\ude80 **Type-safe**: Built with Pydantic for full type safety and validation\n- \ud83d\udd27 **Easy to use**: Simple, intuitive API design\n- \ud83d\udee1\ufe0f **Robust**: Comprehensive error handling and retry logic\n- \ud83d\udcda **Well documented**: Extensive documentation and examples\n- \ud83d\udd04 **Async ready**: Built for both sync and async usage patterns\n- \ud83c\udfaf **Production ready**: Battle-tested in production environments\n\n## Installation\n\n```bash\npip install cufinder-py\n```\n\n## Quick Start\n\n```python\nfrom cufinder import CufinderSDK\n\n# Initialize the SDK\nsdk = CufinderSDK(api_key=\"your-api-key-here\")\n\n# Get company domain from company name\ncompany = sdk.cuf(\n company_name=\"TechCorp\",\n country_code=\"US\"\n)\nprint(company.domain) # 'techcorp.com'\n\n# Enrich LinkedIn profile\nprofile = sdk.epp(\n linkedin_url=\"https://linkedin.com/in/johndoe\"\n)\nprint(profile.person.full_name) # 'John Doe'\n\n# Search local businesses\nbusinesses = sdk.lbs(\n name=\"coffee shop\",\n city=\"San Francisco\",\n state=\"CA\"\n)\nprint(f\"Found {businesses.total} businesses\")\n```\n\n## API Services\n\n### CUF - Company URL Finder\nFind the official website URL of a company based on its name.\n\n```python\ndomain = sdk.cuf(\n company_name=\"Microsoft\",\n country_code=\"US\"\n)\n```\n\n### EPP - Email Pattern Predictor\nEnrich LinkedIn profiles to get person and company data.\n\n```python\nprofile = sdk.epp(\n linkedin_url=\"https://linkedin.com/in/satyanadella\"\n)\n```\n\n### LBS - Local Business Search\nSearch for local businesses by location, industry, or name.\n\n```python\nbusinesses = sdk.lbs(\n name=\"restaurant\",\n city=\"New York\",\n state=\"NY\",\n industry=\"food\"\n)\n```\n\n## Configuration\n\n```python\nsdk = CufinderSDK(\n api_key=\"your-api-key\",\n base_url=\"https://api.cufinder.io/v2\", # Optional\n timeout=30, # Optional, default 30 seconds\n max_retries=3 # Optional, default 3 retries\n)\n```\n\n## Error Handling\n\nThe SDK provides comprehensive error handling with specific exception types:\n\n```python\nfrom cufinder import (\n CufinderError,\n AuthenticationError,\n ValidationError,\n RateLimitError,\n CreditLimitError,\n NetworkError\n)\n\ntry:\n result = sdk.cuf(company_name=\"TechCorp\", country_code=\"US\")\nexcept ValidationError as e:\n print(f\"Validation error: {e}\")\nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e}\")\nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Retry after: {e.retry_after} seconds\")\nexcept CreditLimitError as e:\n print(f\"Credit limit exceeded: {e}\")\nexcept NetworkError as e:\n print(f\"Network error: {e}\")\nexcept CufinderError as e:\n print(f\"API error: {e}\")\n```\n\n## Advanced Usage\n\n### Direct Client Access\n\nFor advanced usage, you can access the underlying HTTP client:\n\n```python\nclient = sdk.get_client()\n\n# Make custom requests\nresponse = client.get(\"/custom-endpoint\", params={\"param\": \"value\"})\n```\n\n### Custom Headers\n\n```python\nresponse = client.post(\n \"/endpoint\",\n data={\"key\": \"value\"},\n headers={\"Custom-Header\": \"value\"}\n)\n```\n\n## Response Models\n\nAll responses are strongly typed using Pydantic models:\n\n```python\nfrom cufinder.models import CufResponse, EppResponse, LbsResponse\n\n# CUF Response\ndomain: CufResponse = sdk.cuf(\"TechCorp\", \"US\")\nprint(domain.domain)\nprint(domain.confidence)\n\n# EPP Response \nprofile: EppResponse = sdk.epp(\"https://linkedin.com/in/johndoe\")\nprint(profile.person.full_name)\nprint(profile.company.name)\n\n# LBS Response\nbusinesses: LbsResponse = sdk.lbs(city=\"San Francisco\")\nprint(businesses.total)\nprint(businesses.businesses[0][\"name\"])\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/CUFinder/cufinder-py.git\ncd cufinder-py\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack src/ tests/\nisort src/ tests/\n```\n\n### Type Checking\n\n```bash\nmypy src/\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- \ud83d\udce7 Email: support@cufinder.io\n- \ud83d\udcd6 Documentation: [https://docs.cufinder.io/python](https://docs.cufinder.io/python)\n- \ud83d\udc1b Issues: [https://github.com/CUFinder/cufinder-py/issues](https://github.com/CUFinder/cufinder-py/issues)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for easily integrating with the CUFinder API",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/CUFinder/cufinder-py/issues",
"Documentation": "https://apidoc.cufinder.io/",
"Homepage": "https://github.com/CUFinder/cufinder-py",
"Repository": "https://github.com/CUFinder/cufinder-py.git"
},
"split_keywords": [
"cufinder",
" api",
" sdk",
" python",
" b2b",
" data-enrichment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1740e6a6312f1fe9d30c47103cf37c07604612475174cec06f09c02a020d653d",
"md5": "27c66c6cb9b9855411c37f5648b6b80f",
"sha256": "a39af2c5ac6c89ac1db5b36e4fdfa2d61f62e3caff3330d27333401bdbb74bb9"
},
"downloads": -1,
"filename": "cufinder_py-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27c66c6cb9b9855411c37f5648b6b80f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28949,
"upload_time": "2025-10-09T09:43:11",
"upload_time_iso_8601": "2025-10-09T09:43:11.338852Z",
"url": "https://files.pythonhosted.org/packages/17/40/e6a6312f1fe9d30c47103cf37c07604612475174cec06f09c02a020d653d/cufinder_py-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a26769efaab9e61f36058b76e27bcce16d69cba496500e3b7fc13284500ff99d",
"md5": "fa8c9f4544fec2e30971df519eae853a",
"sha256": "ac9026e40a8cd58fc750cf89d547534e4f132c179ca1bcad288f5de04b9d6ebe"
},
"downloads": -1,
"filename": "cufinder_py-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "fa8c9f4544fec2e30971df519eae853a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26682,
"upload_time": "2025-10-09T09:43:13",
"upload_time_iso_8601": "2025-10-09T09:43:13.488148Z",
"url": "https://files.pythonhosted.org/packages/a2/67/69efaab9e61f36058b76e27bcce16d69cba496500e3b7fc13284500ff99d/cufinder_py-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 09:43:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CUFinder",
"github_project": "cufinder-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"lcname": "cufinder-py"
}
JSON
