Metadata-Version: 2.4
Name: pounce-agent-data
Version: 2.1.0
Summary: Python SDK for the Pounce v2 Entity API — search, look up, and enrich 65M+ verified B2B companies.
Project-URL: Homepage, https://pounce.ch/api
Project-URL: Documentation, https://pounce.ch/skill.md
Project-URL: Repository, https://gitlab.pounce.ch/pounce/pounce
Author-email: Pounce <hello@pounce.ch>
License-Expression: MIT
Keywords: agents,ai,api,b2b,companies,pounce,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Description-Content-Type: text/markdown

# pounce-agent-data

Python SDK for the **Pounce v2 Entity API** — search, look up, and enrich 65M+ verified B2B companies.

## Installation

```bash
pip install pounce-agent-data
```

## Quick Start

```python
from pounce_agent_data import PounceClient

client = PounceClient(api_key="your_key")

# Search with advanced filters
results, rate = client.search(
    q="AI companies", country="CH", city="Zurich",
    founded_min=2020, sort="newest", limit=10
)
for company in results["items"]:
    print(company["canonical_name"], company["primary_domain"])

# AI semantic search (2 credits)
results, rate = client.semantic_search("fintech startups in Switzerland")

# Lookup by domain
company, rate = client.lookup("stripe.com")

# Full company profile
detail, rate = client.detail(entity_id=12345)

# Analytics
countries, rate = client.analytics_countries()
sectors, rate = client.analytics_sectors(country="CH")
```

## Generic Request

For any endpoint not covered by a convenience method — including new endpoints
added after this SDK version — use `request()`:

```python
data, rate = client.request("GET", "/entities/export", params={"country": "CH", "format": "csv"})
data, rate = client.request("POST", "/webhooks", json={"url": "https://...", "events": ["entity.updated"]})
```

## Authentication

Pass your API key directly or set the `POUNCE_API_KEY` environment variable:

```bash
export POUNCE_API_KEY=your_key
```

```python
client = PounceClient()  # reads from env
```

## API Methods

### Search & Discovery

| Method | Credits | Description |
|--------|---------|-------------|
| `search()` | 1 | Filter by keyword, country, city, founding year, employee range, domain, sort |
| `semantic_search()` | 2 | AI-powered natural language search |
| `autocomplete()` | 0 | Fast name autocomplete for type-ahead |
| `lookup(domain)` | 1 | Find a company by domain |

### Entity Detail

| Method | Credits | Description |
|--------|---------|-------------|
| `detail(entity_id)` | 1 | Full company profile |
| `officers(entity_id)` | 1 | Company officers & key people |
| `changes(entity_id)` | 1 | Entity change timeline (Developer+) |
| `similar(entity_id)` | 2 | Find similar entities via vector search |

### Bulk & Export

| Method | Credits | Description |
|--------|---------|-------------|
| `bulk_lookup(domains)` | 1/found | Bulk lookup up to 100 domains |
| `export()` | 5 | Export as CSV/JSON (Developer+) |

### Analytics

| Method | Credits | Description |
|--------|---------|-------------|
| `analytics_overview()` | 1 | Platform statistics & coverage (Developer+) |
| `analytics_countries()` | 1 | Entity counts per country (Developer+) |
| `analytics_sectors()` | 1 | Top sectors for a country (Developer+) |
| `analytics_formations()` | 1 | Entity formation trends (Developer+) |
| `analytics_geography()` | 1 | Entity density by city (Developer+) |

### Webhooks

| Method | Credits | Description |
|--------|---------|-------------|
| `create_webhook()` | 0 | Register a webhook URL (Developer+) |
| `list_webhooks()` | 0 | List registered webhooks (Developer+) |
| `delete_webhook()` | 0 | Delete a webhook |
| `test_webhook()` | 0 | Send a test event |

### Other

| Method | Credits | Description |
|--------|---------|-------------|
| `match_score(a, b)` | 3 | Similarity score between two companies (Business+) |
| `stats()` | 0 | Public platform statistics |
| `request(method, path)` | varies | Generic request for any v2 endpoint |

## Search Filters

```python
results, rate = client.search(
    q="fintech",              # keyword search
    country="CH",             # ISO country code
    city="Zurich",            # city name
    founded_min=2020,         # minimum founding year
    founded_max=2025,         # maximum founding year
    first_seen_after="2025-01-01",  # only entities indexed after this date
    employee_range="11-50",   # 1-10, 11-50, 51-200, 201-500, 500+
    has_domain=True,          # only companies with a known domain
    sort="newest",            # relevance, newest, oldest, quality
    limit=25,
    offset=0,
)
```

## Rate Limits

Every response includes rate limit info:

```python
results, rate = client.search(q="test")
print(rate.remaining)      # calls remaining this month
print(rate.credits_used)   # credits consumed by this call
```

## Plans

| Plan | Monthly Calls | Rate/Min |
|------|--------------|----------|
| Free | 100 | 30 |
| Developer (€19/mo) | 5,000 | 60 |
| Business (€49/mo) | 25,000 | 300 |
| Enterprise (custom) | 200,000 | 1,000 |

## Links

- [API Documentation](https://pounce.ch/api)
- [Get an API Key](https://pounce.ch/register)
