Metadata-Version: 2.4
Name: ticketsdata-client
Version: 1.0.3
Summary: Async Python client for TicketsData API
Author-email: TicketsData <info@ticketsdata.com>
License: MIT
Project-URL: Homepage, https://ticketsdata.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9.0
Dynamic: license-file

# 🧩 ticketsdata-client

**Async Python SDK for [TicketsData.com](https://ticketsdata.com)**  
Supports all marketplaces: **Ticketmaster**, **StubHub**, **Gametime**, **SeatGeek**, **TickPick**, and **VividSeats** with one unified interface.

Every SDK response is automatically tagged with:

- `platform`
- `event_url`
- optional `mode` / `qty`
- `http_status`
- `started_at`
- `response_ms`
- and the untouched API payload under `result`

---

## 🚀 Features

- **Async + concurrent** — powered by `aiohttp`, optimized for high throughput  
- **Multi-platform support** — fetch from all major ticketing marketplaces  
- **Automatic metadata tagging** — platform + timing info added to each result  
- **Configurable concurrency** — control how many requests run in parallel  
- **Retry & timeout logic** built in  
- **Flexible job loading** — JSON, DB, queues, CSV  

---

## ⚙️ Installation

```bash
pip install ticketsdata-client
```

---

## 🧠 Quick Usage

```python
import asyncio
import json
from ticketsdata_client import TicketsDataClient

async def main():
    client = TicketsDataClient(
        username="YOUR_EMAIL",
        password="YOUR_PASSWORD",
        concurrency=10,
        timeout=30,
        include_metadata=True
    )

    jobs = [
        {"platform": "ticketmaster", "event_url": "https://www.ticketmaster.com/lady-gaga-the-mayhem-ball-boston-massachusetts-03-29-2026/event/01006323DE0B7BE1"},
        {"platform": "stubhub",     "event_url": "https://www.stubhub.com/sabrina-carpenter-los-angeles-tickets-11-23-2025/event/157413810/"},
        {"platform": "seatgeek",    "event_url": "https://seatgeek.com/sabrina-carpenter-tickets/los-angeles-california-crypto-com-arena-2025-11-23-7-pm/concert/17400739"},
        {"platform": "vividseats",  "event_url": "https://www.vividseats.com/sabrina-carpenter-tickets-los-angeles-cryptocom-arena-11-23-2025--concerts-pop/production/5599667"},
        {"platform": "tickpick",    "event_url": "https://www.tickpick.com/buy-playboi-carti-tickets-state-farm-arena-ga-12-1-25-7pm/7364698/"},
        {"platform": "gametime",    "event_url": "6908d769dfe85fe8ad73cd62", "mode": "all"}
    ]

    results = await client.fetch_many(jobs)

    for r in results:
        ##Valid JSON with indention per each event
        print(json.dumps(r, indent=2, ensure_ascii=False))
        

    await client.close()

asyncio.run(main())

```

---

## 🧾 Example `jobs.json`

```json
[
  {"platform": "ticketmaster", "event_url": "https://www.ticketmaster.com/lady-gaga-the-mayhem-ball-boston-massachusetts-03-29-2026/event/01006323DE0B7BE1"},
  {"platform": "stubhub",     "event_url": "https://www.stubhub.com/sabrina-carppenter-los-angeles-tickets-11-23-2025/event/157413810/"},
  {"platform": "seatgeek",    "event_url": "https://seatgeek.com/sabrina-carpenter-tickets/los-angeles-california-crypto-com-arena-2025-11-23-7-pm/concert/17400739"},
  {"platform": "vividseats",  "event_url": "https://www.vividseats.com/sabrina-carpenter-tickets-los-angeles-cryptocom-arena-11-23-2025--concerts-pop/production/5599667"},
  {"platform": "tickpick",    "event_url": "https://www.tickpick.com/buy-playboi-carti-tickets-state-farm-arena-ga-12-1-25-7pm/7364698/"},
  {"platform": "gametime",    "event_url": "6908d769dfe85fe8ad73cd62", "mode": "all"}
]
```

Load from file:

```python
import json, asyncio
from ticketsdata_client import TicketsDataClient

async def main():
    with open("jobs.json") as f:
        jobs = json.load(f)

    client = TicketsDataClient(username="YOUR_EMAIL", password="YOUR_PASSWORD", include_metadata=True)
    results = await client.fetch_many(jobs)
    print(results)

    await client.close()

asyncio.run(main())
```

---

## 💡 Understanding `concurrency`

Concurrency controls how many API requests run **simultaneously**.

```python
client = TicketsDataClient(concurrency=10)
```

This allows **10 requests in parallel**, greatly improving throughput.

### Recommended settings
- **3–5** → safe, low quota usage  
- **10–20** → optimal speed  
- **30+** → only on dedicated plans  

Shared plans (Starter/Pro) include **soft concurrency limits** to ensure stable performance.  
Dedicated environments remove these limits entirely.

---

## ⚙️ Parameters

| Parameter            | Type | Default                           | Description                                   |
|----------------------|------|-----------------------------------|-----------------------------------------------|
| `username`           | str  | required                          | TicketsData username                           |
| `password`           | str  | required                          | TicketsData password                           |
| `base_url`           | str  | `"https://ticketsdata.com/fetch"` | API endpoint                                   |
| `concurrency`        | int  | 5                                 | Number of parallel requests                    |
| `timeout`            | int  | 25                                | Timeout per request                            |
| `max_retries`        | int  | 2                                 | Retry count for network errors                 |
| `include_metadata`   | bool | True                              | Attach platform + timing metadata to results   |

---

## 📚 Result Format (inside `"result"`)

```json
{
  "platform": "ticketmaster",
  "event_url": "https://www.ticketmaster.com/...",
  "http_status": 200,
  "response_ms": 1388,
  "result": {
    "status": 200,
    "body": {
      "status_code": 200,
      "event_id": "18006342AD8BE4D8",
      "items": { "totalListings": 1432, "offers": [...] },
      "response_s": 0.92,
      "quota_remaining": 9924
    },
    "response_s": 0.923
  }
}
```

---

## 🧩 License

MIT © TicketsData.com

---

## 🧠 Support

- **Website:** https://ticketsdata.com  
- **Email:** info@ticketsdata.com  
