Metadata-Version: 2.4
Name: artmarketapi
Version: 1.0.0
Summary: Official Python SDK for the ArtMarketAPI — access auction records, comparable sales, artist data, market trends, valuations, and more.
Project-URL: Homepage, https://artmarketapi.com
Project-URL: Documentation, https://artmarketapi.com/docs
Project-URL: Repository, https://github.com/ArtMarketAPI/artmarketapi-python
Project-URL: Issues, https://github.com/ArtMarketAPI/artmarketapi-python/issues
Author-email: ArtMarketAPI <support@artcollection.io>
License-Expression: MIT
License-File: LICENSE
Keywords: api,art,art-market,auction,market,sdk,valuation
Classifier: Development Status :: 5 - Production/Stable
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: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# ArtMarketAPI — Python SDK

Official Python SDK for the [ArtMarketAPI](https://artmarketapi.com). Access auction records, comparable sales, artist data, market trends, AI valuations, and more.

## Installation

```bash
pip install artmarketapi
```

## Quick Start

```python
from artmarketapi import ArtMarketAPI

client = ArtMarketAPI("amapi_live_xxxxx_xxxxx")

# Search for an artist
results = client.search.artists("Picasso")
artist_id = results["data"][0]["id"]

# Get their auction records
records = client.auction_records.list(
    artist=artist_id,
    category="painting",
    start_date="2024-01-01",
    limit=25,
)

for record in records["data"]:
    print(f"{record['title']} — ${record.get('usd_hammer_price', 'N/A'):,}")
```

## Authentication

All requests require an API key. Get yours at [artmarketapi.com](https://artmarketapi.com):

1. Sign up at [artmarketapi.com](https://artmarketapi.com)
2. Navigate to **Settings > API Keys**
3. Click **Generate New Key**
4. Copy and securely store your key (it won't be shown again)

```python
import os
from artmarketapi import ArtMarketAPI

client = ArtMarketAPI(os.environ["ARTMARKET_API_KEY"])
```

> **Never hard-code API keys.** Use environment variables or a secrets manager.

## API Reference

### Auction Records

```python
# List with filters
records = client.auction_records.list(
    artist="507f1f77bcf86cd799439011",
    category="painting",        # painting | print | sculpture | photography | drawing | other
    start_date="2024-01-01",    # ISO 8601
    end_date="2025-01-01",
    min_price=10000,            # USD
    max_price=500000,
    lot_performance="above",    # upcoming | above | within | below | not_sold | pulled
    sort_by="usd_hammer_price", # sale_date | usd_hammer_price | created_at
    sort_order="desc",
    include_analytics=True,     # requires artist filter
    limit=25,
    page=1,
)

# Get single record
record = client.auction_records.get("507f1f77bcf86cd799439012")
```

### Comparable Sales

AI-optimized endpoint for finding similar artworks. Returns cleaner, more structured data ideal for AI integration.

```python
# Find comparables
comps = client.comparable_sales.list(
    category="painting",
    medium="oil",
    min_width=90,
    max_width=110,
    min_height=70,
    max_height=90,
    years_back=2,
)

# Get aggregate statistics only
summary = client.comparable_sales.summary(
    artist="507f1f77bcf86cd799439011",
    category="painting",
)
```

### Artists

```python
# Get artist details
artist = client.artists.get("507f1f77bcf86cd799439011")

# Past auction records
history = client.artists.past_auction_records(
    "507f1f77bcf86cd799439011",
    page=1,
    sort_by="hammer_price",
)

# Sell-through rates
rates = client.artists.sell_through_rates("507f1f77bcf86cd799439011")

# SLPAE analytics
slpae = client.artists.slpae("507f1f77bcf86cd799439011")
```

### Search

```python
results = client.search.artists("Picasso", limit=10, page=0)

# results["data"] = [{"id": "...", "name": "Pablo Picasso"}, ...]
```

### Market Trends

```python
# Full market overview
overview = client.market_trends.overview(category="painting")

# Market heat index (0-100)
heat = client.market_trends.heat(category="painting", months=6)

# Emerging artists
emerging = client.market_trends.emerging()

# Category performance rankings
categories = client.market_trends.categories()

# Market regime for an artist (bull/bear/sideways)
regime = client.market_trends.regime("507f1f77bcf86cd799439011")

# Market sentiment
sentiment = client.market_trends.sentiment()
```

### Price Database

Advanced search with AI-powered semantic search.

```python
results = client.price_database.search(
    artist="507f1f77bcf86cd799439011",
    description="blue abstract oil painting",  # semantic search
    category="painting",
    min_hammer_price=5000,
    sort_option="hammer_price_desc",
)
```

### Valuation

AI-powered artwork valuation.

```python
# Basic valuation
valuation = client.valuation.estimate(
    artist="Pablo Picasso",
    width_cm=100,
    height_cm=80,
    category="painting",
    medium="Oil on canvas",
)

# Advanced analysis with market context
analysis = client.valuation.analysis(
    artist="Pablo Picasso",
    width_cm=100,
    height_cm=80,
    category="painting",
)

# Find similar artworks by description
similar = client.valuation.describe(
    artist="Pablo Picasso",
    category="painting",
    width=100,
    height=80,
    description="Blue period portrait",
)
```

## Error Handling

The SDK raises typed exceptions you can catch and handle:

```python
from artmarketapi import (
    ArtMarketAPI,
    ArtMarketAPIError,
    AuthenticationError,
    RateLimitError,
    PlanUpgradeRequiredError,
    NotFoundError,
)

try:
    records = client.auction_records.list(artist="...")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
    print(f"Remaining: {e.rate_limit.remaining}")
except AuthenticationError:
    print("Invalid API key")
except PlanUpgradeRequiredError:
    print("Upgrade your plan to access this endpoint")
except NotFoundError:
    print("Resource not found")
except ArtMarketAPIError as e:
    print(f"API error: {e.code} - {e}")
    print(f"Request ID: {e.request_id}")
```

## Rate Limits

Rate limit info is available after each request:

```python
records = client.auction_records.list(artist="...")

print(client.rate_limit)
# RateLimitInfo(limit=60, remaining=59, reset=1679529600)
```

| Plan       | Requests/Min | Requests/Day | Max Page Size |
|------------|-------------|--------------|---------------|
| Free       | 10          | 200          | 10            |
| Starter    | 30          | 2,000        | 25            |
| Pro        | 60          | 10,000       | 50            |
| Enterprise | 120         | 50,000       | 100           |

## Context Manager

The client supports use as a context manager for automatic cleanup:

```python
with ArtMarketAPI("amapi_live_xxxxx_xxxxx") as client:
    records = client.auction_records.list(category="painting")
```

## Configuration

```python
client = ArtMarketAPI(
    "amapi_live_xxxxx_xxxxx",

    # Optional: override base URL (for testing or self-hosted)
    base_url="https://api.artmarketapi.com/api/v1",

    # Optional: request timeout in seconds (default: 30)
    timeout=60.0,

    # Optional: bring your own httpx.Client
    http_client=my_httpx_client,
)
```

## Type Hints

The SDK ships with a `py.typed` marker and full type annotations. All response types are available in `artmarketapi.types`:

```python
from artmarketapi.types import (
    AuctionRecord,
    ComparableSale,
    Artist,
    MarketHeat,
    ValuationResult,
)
```

## Requirements

- Python >= 3.9
- [httpx](https://www.python-httpx.org/) >= 0.25.0
- An ArtMarketAPI key from [artmarketapi.com](https://artmarketapi.com)

## License

MIT
