Metadata-Version: 2.4
Name: vanda-api
Version: 0.1.1
Summary: Official Python SDK for Vanda Analytics Data API
Project-URL: Homepage, https://gitlab.com/yourusername/vanda-api
Project-URL: Documentation, https://gitlab.com/yourusername/vanda-api#readme
Project-URL: Repository, https://gitlab.com/yourusername/vanda-api
Project-URL: Issues, https://gitlab.com/yourusername/vanda-api/-/issues
Author-email: Jonathan Aina <Jonathan.Aina@vanda.com>
License: MIT
License-File: LICENSE
Keywords: analytics,api,finance,market-data,retail-trading,vanda
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: respx>=0.20.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0; extra == 'pandas'
Description-Content-Type: text/markdown

# Vanda Analytics Data API SDK

Official Python SDK for the Vanda Analytics Data API.

## Installation

```bash
pip install vanda-api
```

For pandas support:

```bash
pip install vanda-api[pandas]
```

## Quick Start

### Synchronous Client

```python
from datetime import date
from vanda import VandaClient

with VandaClient(token="YOUR_TOKEN_HERE") as client:
    data = client.get_timeseries(
        symbol="TSLA",
        start_date=date(2025, 12, 1),
        end_date=date(2025, 12, 31),
        fields=["retail_net_turnover", "retail_buy_turnover"],
    )
    print(f"Retrieved {len(data)} records")
```

```python
from vanda import VandaClient

# Pass credentials directly
with VandaClient(email="your_email@example.com", password="your_password") as client:
    data = client.get_timeseries(
        symbol="TSLA",
        start_date="2025-12-01",
        end_date="2025-12-31",
        fields=["retail_net_turnover"],
    )

```

### Recommended to use environment variables

```python
export VANDA_LOGIN_EMAIL="your_email@example.com"
export VANDA_PASSWORD="your_password"
```

### Asynchronous Client

```python
import asyncio
from datetime import date
from vanda import AsyncVandaClient

async def main():
    async with AsyncVandaClient(token="YOUR_TOKEN_HERE") as client:
        data = await client.get_timeseries(
            symbol="TSLA",
            start_date=date(2025, 12, 1),
            end_date=date(2025, 12, 31),
            fields=["retail_net_turnover"],
        )
        print(f"Retrieved {len(data)} records")

asyncio.run(main())
```

```python
import asyncio
from vanda import AsyncVandaClient

async def main():
    async with AsyncVandaClient(email="your_email@example.com", password="your_password") as client:
        data = await client.get_timeseries(
            symbol="TSLA",
            start_date="2025-12-01",
            end_date="2025-12-31",
            fields=["retail_net_turnover"],
        )

asyncio.run(main())
```

### Recommended to use environment variables

```python
export VANDA_LOGIN_EMAIL="your_email@example.com"
export VANDA_PASSWORD="your_password"
```

## Authentication

Set your API token via environment variable:

```bash
export VANDA_API_TOKEN="your_token_here"
```

or

```bash
export VANDA_LOGIN_EMAIL="your_email@example.com"
export VANDA_PASSWORD="your_password"
```

Or pass directly:

```python
client = VandaClient(token="your_token_here")
```

or

```python
client = VandaClient(email="your_email@example.com", password="your_password")
```

## Features

- Sync and async clients with consistent interfaces
- Automatic retry with exponential backoff
- Comprehensive error handling
- Job polling for async operations
- Export utilities (CSV, JSONL)
- Optional pandas support
- Type hints throughout

## API Methods

### Timeseries Data

- `get_timeseries()` - Get timeseries for a single symbol
- `get_timeseries_many()` - Get timeseries for multiple symbols
- `get_leaderboard()` - Get ranked leaderboard data

### Bulk Operations

- `bulk_securities()` - Bulk fetch securities data
- `get_daily_snapshot()` - Get daily snapshot for many securities

### Job Management

- `create_bulk_securities_job()` - Create async job
- `poll_job()` - Poll job until completion
- `get_job_status()` - Get job status
- `export_job_result()` - Export job result to file
- `stream_job_result()` - Stream job result to file

### Export Operations

- `export_timeseries()` - Export timeseries to file

### Metadata

- `list_fields()` - List available fields
- `list_intervals()` - List available intervals
- `list_securities()` - List available securities

## Examples

See `examples/` directory for complete usage examples.

## Requirements

- Python 3.9+
- httpx

## Development

```bash
git clone https://gitlab.com/yourusername/vanda-api.git
cd vanda-api
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install
pytest
```

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions, please open an issue on GitLab.
