Official SDK for the ArtMarketAPI. Access auction records, comparable sales, artist data, market trends, AI valuations, and more.
npm install artmarketapi
# or
yarn add artmarketapi
# or
pnpm add artmarketapiimport { ArtMarketAPI } from "artmarketapi";
const client = new ArtMarketAPI({
apiKey: "amapi_live_xxxxx_xxxxx",
});
// Search for an artist
const search = await client.search.artists({ name: "Picasso" });
const artistId = search.data[0].id;
// Get their auction records
const records = await client.auctionRecords.list({
artist: artistId,
category: "painting",
start_date: "2024-01-01",
limit: 25,
});
console.log(records.data); // AuctionRecord[]All requests require an API key. Get yours at artmarketapi.com:
- Sign up at artmarketapi.com
- Navigate to Settings > API Keys
- Click Generate New Key
- Copy and securely store your key (it won't be shown again)
const client = new ArtMarketAPI({
apiKey: process.env.ARTMARKET_API_KEY!,
});Never expose your API key in client-side code. Use environment variables and keep keys on the server.
// List with filters
const records = await client.auctionRecords.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
const record = await client.auctionRecords.get("507f1f77bcf86cd799439012");AI-optimized endpoint for finding similar artworks. Returns cleaner, more structured data ideal for AI integration.
// Find comparables
const comps = await client.comparableSales.list({
category: "painting",
medium: "oil",
min_width: 90,
max_width: 110,
min_height: 70,
max_height: 90,
years_back: 2,
});
// Get aggregate statistics only
const summary = await client.comparableSales.summary({
artist: "507f1f77bcf86cd799439011",
category: "painting",
});// Get artist details
const artist = await client.artists.get("507f1f77bcf86cd799439011");
// Past auction records
const history = await client.artists.pastAuctionRecords("507f1f77bcf86cd799439011", {
page: 1,
sortBy: "hammer_price",
});
// Sell-through rates
const rates = await client.artists.sellThroughRates("507f1f77bcf86cd799439011");
// SLPAE analytics
const slpae = await client.artists.slpae("507f1f77bcf86cd799439011");const results = await client.search.artists({
name: "Picasso",
limit: 10,
page: 0,
});
// results.data = [{ id: "...", name: "Pablo Picasso" }, ...]// Full market overview
const overview = await client.marketTrends.overview({ category: "painting" });
// Market heat index (0-100)
const heat = await client.marketTrends.heat({ category: "painting", months: 6 });
// Emerging artists
const emerging = await client.marketTrends.emerging();
// Category performance rankings
const categories = await client.marketTrends.categories();
// Market regime for an artist (bull/bear/sideways)
const regime = await client.marketTrends.regime("507f1f77bcf86cd799439011");
// Market sentiment
const sentiment = await client.marketTrends.sentiment();Advanced search with AI-powered semantic search.
const results = await client.priceDatabase.search({
artist: "507f1f77bcf86cd799439011",
description: "blue abstract oil painting", // semantic search
category: "painting",
min_hammer_price: 5000,
sort_option: "hammer_price_desc",
});AI-powered artwork valuation.
// Basic valuation
const valuation = await client.valuation.estimate({
artist: "Pablo Picasso",
width_cm: 100,
height_cm: 80,
category: "painting",
medium: "Oil on canvas",
});
// Advanced analysis with market context
const analysis = await client.valuation.analysis({
artist: "Pablo Picasso",
width_cm: 100,
height_cm: 80,
category: "painting",
});
// Find similar artworks by description
const similar = await client.valuation.describe({
artist: "Pablo Picasso",
category: "painting",
width: 100,
height: 80,
description: "Blue period portrait",
});The SDK throws typed errors you can catch and handle:
import {
ArtMarketAPI,
ArtMarketAPIError,
AuthenticationError,
RateLimitError,
PlanUpgradeRequiredError,
NotFoundError,
} from "artmarketapi";
try {
const records = await client.auctionRecords.list({ artist: "..." });
} catch (error) {
if (error instanceof RateLimitError) {
console.log(`Rate limited. Retry after ${error.retryAfter}s`);
console.log(`Remaining: ${error.rateLimit.remaining}`);
} else if (error instanceof AuthenticationError) {
console.log("Invalid API key");
} else if (error instanceof PlanUpgradeRequiredError) {
console.log("Upgrade your plan to access this endpoint");
} else if (error instanceof NotFoundError) {
console.log("Resource not found");
} else if (error instanceof ArtMarketAPIError) {
console.log(`API error: ${error.code} - ${error.message}`);
console.log(`Request ID: ${error.requestId}`);
}
}Rate limit info is available after each request:
const records = await client.auctionRecords.list({ artist: "..." });
console.log(client.rateLimit);
// { 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 |
const client = new ArtMarketAPI({
apiKey: "amapi_live_xxxxx_xxxxx",
// Optional: override base URL (for testing or self-hosted)
baseUrl: "https://api.artmarketapi.com/api/v1",
// Optional: request timeout in ms (default: 30000)
timeout: 60000,
// Optional: custom fetch (e.g., for Node 16 or testing)
fetch: customFetchImpl,
});The SDK is written in TypeScript and exports all types:
import type {
AuctionRecord,
ComparableSale,
Artist,
MarketHeat,
ValuationResult,
Category,
LotPerformance,
} from "artmarketapi";- Node.js >= 18 (or any environment with
fetch) - An ArtMarketAPI key from artmarketapi.com
MIT