Metadata-Version: 2.4
Name: vswarehouse
Version: 0.1.0
Summary: Python client for the vs-warehouse statistical data API
Project-URL: Homepage, https://api.virtus-solutions.io
Project-URL: Documentation, https://api.virtus-solutions.io/docs
Project-URL: Repository, https://github.com/virtus-solutions/vswarehouse-python
Author-email: Virtus Solutions <api@virtus-solutions.io>
License: MIT
Keywords: api,australia,economics,new-zealand,statistics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: pandas>=1.5
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pandas; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: responses; extra == 'dev'
Description-Content-Type: text/markdown

# vswarehouse

Python client for the [vs-warehouse](https://api.virtus-solutions.io) statistical data API — macro and economic time series for New Zealand, Australia, and more.

## Installation

```bash
pip install vswarehouse
```

## Quick start

```python
from vswarehouse import Client

client = Client("vs_your_api_key")

# List all available series
series = client.list()

# Get metadata for a series
meta = client.info("nz_cpi")

# Fetch data as a pandas DataFrame
df = client.get("nz_cpi", start="2020-01-01")
print(df.head())
```

## Authentication

Pass your key directly or set the `VS_API_KEY` environment variable:

```bash
export VS_API_KEY=vs_your_api_key
```

```python
client = Client()  # reads VS_API_KEY automatically
```

Get a free API key at [api.virtus-solutions.io](https://api.virtus-solutions.io).

## API reference

### `Client(api_key, base_url)`

| Method | Returns | Description |
|---|---|---|
| `list()` | `list[dict]` | All available series with metadata |
| `info(name)` | `dict` | Metadata for a single series |
| `get(name, start, end, format)` | `DataFrame` | Time-series data |

### `get()` parameters

| Param | Type | Description |
|---|---|---|
| `name` | `str` | Series identifier, e.g. `"nz_cpi"` |
| `start` | `str` | ISO date lower bound, e.g. `"2020-01-01"` |
| `end` | `str` | ISO date upper bound |
| `format` | `str` | `"json"` (default) or `"csv"` |

## Exceptions

| Exception | When |
|---|---|
| `AuthenticationError` | Invalid or inactive API key |
| `RateLimitError` | Daily free-tier limit reached |
| `NotFoundError` | Series not found |
| `APIError` | Other HTTP errors |

## License

MIT
