Museum Artworks — Met + Cleveland Unified Search (Apify Actor)

Search artwork records from the Metropolitan Museum of Art and the Cleveland Museum of Art in a unified JSON schema. Returns one record per artwork with artist, title, date range, medium, dimensions, images, credit line, source URL, license posture, and free-form tags.

Source coverage

Source	Auth	Captcha	Endpoint	Records	License / ToS
Metropolitan Museum of Art	none	none	https://collectionapi.metmuseum.org/public/collection/v1/	417,474+	Open Access under CC0 (metmuseum.github.io); robot-friendly public API; no documented rate limit, see "Polite use" below
Cleveland Museum of Art	none	none	https://openaccess-api.clevelandart.org/api/artworks	68,758+	Open Access API; images distributed under share_license_status (CC0 / CC-BY-SA etc. exposed per record)

Both endpoints return JSON, no proxy / captcha / JS rendering needed, no auth, no API key. They are public research APIs maintained by each museum; we honor each museum's published ToS (request rate ~1 req/sec, descriptive User-Agent).

What it does

• Two source adapters (met, cleveland), one orchestrator. The museum="both" mode merges results (Met IDs first, then Cleveland). Each adapter is independent — one source failing doesn't block the other (gotcha #37 — independent clients per source).
• Output is one dataset record per artwork, harmonized to a single schema across both sources:
  • source: "met" | "cleveland"
  • sourceId: museum-side identifier (objectID / accession_number)
  • artist + bio, title, date display string, dateEarliest/dateLatest (integer years, nullable)
  • medium, dimensions, department, classification, culture list
  • isPublicDomain Boolean (image license flag)
  • primaryImage / primaryImageSmall URLs, additionalImages[]
  • creditLine, sourceUrl, tags[]
• Outputs are pushed to the default Apify dataset via Actor.pushData(...) per gotcha #13.
• Smoke-tested inputs museum=met and museum=cleveland both return non-null records on a real query.

Input

Field	Type	Default	Description
museum	select	"both"	met | cleveland | both
query	textfield	"van gogh"	Free-text search. Met: maps to ?q=. Cleveland: maps to ?q=.
hasImages	checkbox	true	Met: limit to records with primaryImage. Cleveland: always image-present when matched.
maxResults	number (1-500)	50	Hard cap on total records returned across all sources.

Output

One dataset record per artwork. See .actor/dataset_schema.json for the full shape. Sample (first record from a museum=met, query=rembrandt, maxResults=3 smoke run, abridged):

{
  "source": "met",
  "sourceId": "437394",
  "title": "Aristotle with a Bust of Homer",
  "artist": "Rembrandt (Rembrandt van Rijn)",
  "artistBio": "Dutch, Leiden 1606–1669 Amsterdam",
  "date": "1653",
  "dateEarliest": 1653,
  "dateLatest": 1653,
  "medium": "Oil on canvas",
  "dimensions": "56 1/2 x 53 3/4 in. (143.5 x 136.5 cm)",
  "department": "European Paintings",
  "classification": "Paintings",
  "culture": [],
  "isPublicDomain": true,
  "primaryImage": "https://images.metmuseum.org/CRDImages/ep/original/DP-30758-001.jpg",
  "primaryImageSmall": "https://images.metmuseum.org/CRDImages/ep/web-large/DP-30758-001.jpg",
  "additionalImages": [],
  "creditLine": "Purchase, special contributions and funds given or bequeathed by friends of the Museum, 1961",
  "sourceUrl": "https://www.metmuseum.org/art/collection/search/437394",
  "tags": ["Portraits", "Paintings"]
}

Limits / gotchas

• maxResults defaults to 50, hard cap 500 (card spec).
• Polite-use: 1 request/second per source. Concurrency is sequential per source; sources run via Promise.allSettled.
• Cleveland's share_license_status is mapped to the unified isPublicDomain Boolean (true when status starts with "CC0", false otherwise). Cleveland images without a permissive license are still returned with their CC URL but downstream consumers should consult share_license_status if their use case requires it.

How to run locally

cd actors/museum-artworks
make install      # npm install apify SDK
make run          # local apify run -p -i .actor/input.json (full SKIP_LOCAL_RUN=1 path is recommended for CI)

Build + push to Apify

$SKIP_LOCAL_RUN=1 bash /Users/hermes-agent/Documents/agent-vault/Companies/apify-actor/bin/publish.sh museum-artworks

bin/publish.sh steps: (1) pre-flight auth + syntax + docker, (2) skipped via SKIP_LOCAL_RUN=1, (3) apify push, (4) cloud smoke (apify call), (5) inventory update.

License

Actor code: MIT (inherited from project template).

Data attribution:

• Metropolitan Museum of Art images: CC0 (Met Open Access).
• Cleveland Museum of Art images: per share_license_status per record (commonly CC0 / CC-BY-SA).

Changelog

• 0.1.0 — initial release. Met + Cleveland.