vanda-api 0.1.1
Official Python SDK for Vanda Analytics Data API
License: MIT
Requires Python: >=3.9
Keywords: analytics, api, finance, market-data, retail-trading, vanda

# 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.