artmarketapi 1.0.0

Official Python SDK for the ArtMarketAPI — access auction records, comparable sales, artist data, market trends, valuations, and more.

ArtMarketAPI — Python SDK

Official Python SDK for the ArtMarketAPI. Access auction records, comparable sales, artist data, market trends, AI valuations, and more.

Installation

pip install artmarketapi

Quick Start

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:

1. Sign up at 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)

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

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

# 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

# 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

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

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

Market Trends

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

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.

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

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:

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:

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

Configuration

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:

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

Requirements

• Python >= 3.9
• httpx >= 0.25.0
• An ArtMarketAPI key from artmarketapi.com

License

MIT