Van Gogh Museum APIvangoghmuseum.nl ↗

"""
Van Gogh Museum Collection API Client
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Any, Dict, List, Optional


class ParseClient:
    """Client for interacting with the Van Gogh Museum Collection API via Parse."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse client.

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.

        Raises:
            ValueError: If API key is not provided and PARSE_API_KEY env var is not set.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "4aa2462d-3c4b-444f-b172-5aff7a992bd6"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError("API key not provided and PARSE_API_KEY env var not set")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make an API call to the Parse endpoint.

        Args:
            endpoint: The endpoint name (e.g., "get_collection")
            method: HTTP method ("GET" or "POST")
            **params: Query/body parameters for the endpoint

        Returns:
            Response JSON as dictionary

        Raises:
            requests.RequestException: If the API call fails
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported HTTP method: {method}")

        response.raise_for_status()
        return response.json()

    def get_collection(
        self,
        query: str = "",
        offset: int = 0
    ) -> Dict[str, Any]:
        """
        Browse or search the museum collection.

        Args:
            query: Search keyword to filter artworks (optional)
            offset: Result offset for pagination

        Returns:
            Dictionary containing items, count, and offset
        """
        return self._call("get_collection", method="GET", query=query, offset=offset)

    def search_artworks(
        self,
        query: str,
        offset: int = 0
    ) -> Dict[str, Any]:
        """
        Search for artworks by keyword.

        Args:
            query: Search keyword (required)
            offset: Result offset for pagination

        Returns:
            Dictionary containing items, count, and offset
        """
        return self._call("search_artworks", method="GET", query=query, offset=offset)

    def get_artwork_detail(self, artwork_id: str) -> Dict[str, Any]:
        """
        Retrieve full details for a single artwork by its ID.

        Args:
            artwork_id: Artwork ID (e.g., 's0031V1962')

        Returns:
            Dictionary containing full artwork details including metadata and images
        """
        return self._call("get_artwork_detail", method="GET", artwork_id=artwork_id)

    def get_collection_filters(self) -> Dict[str, Any]:
        """
        Retrieve available filter categories and their values for the collection.

        Returns:
            Dictionary containing list of available filters with categories and values
        """
        return self._call("get_collection_filters", method="GET")


def main():
    """Practical workflow demonstrating the Van Gogh Museum Collection API."""
    # Initialize client
    client = ParseClient()

    print("=" * 80)
    print("VAN GOGH MUSEUM COLLECTION EXPLORER")
    print("=" * 80)

    # Step 1: Get available filters to understand what we can search
    print("\n[STEP 1] Fetching available collection filters...")
    try:
        filters_response = client.get_collection_filters()
        filters_data = filters_response.get("data", {})
        filters_list = filters_data.get("filters", [])
        print(f"✓ Available filter categories: {len(filters_list)}")
        for filter_item in filters_list[:3]:
            category = filter_item.get("category", "Unknown")
            total_options = filter_item.get("total_options", 0)
            print(f"  - {category} ({total_options} options)")
    except Exception as e:
        print(f"✗ Error fetching filters: {e}")
        return

    # Step 2: Search for artworks using a specific query
    search_term = "Sunflowers"
    print(f"\n[STEP 2] Searching for artworks matching '{search_term}'...")
    try:
        search_results = client.search_artworks(query=search_term, offset=0)
        search_data = search_results.get("data", {})
        total_count = search_data.get("count", 0)
        items = search_data.get("items", [])

        if total_count == 0:
            print(f"✗ No artworks found for '{search_term}'")
            return

        print(f"✓ Found {total_count} artwork(s)")
        print(f"  Displaying first {min(3, len(items))} results...\n")
    except Exception as e:
        print(f"✗ Error during search: {e}")
        return

    # Step 3: Process each search result and fetch detailed information
    detailed_artworks = []
    for idx, item in enumerate(items[:3], 1):
        artwork_id = item.get("id")
        title = item.get("title", "Unknown")
        creator = item.get("creator", "Unknown")
        position = item.get("position", "N/A")

        print(f"[Artwork {idx}] {title}")
        print(f"  ID: {artwork_id}")
        print(f"  Creator: {creator if creator else 'Unknown'}")
        print(f"  Position in collection: {position}")

        try:
            # Fetch detailed information for this artwork
            artwork_detail_response = client.get_artwork_detail(artwork_id)
            artwork_detail = artwork_detail_response.get("data", {})
            detailed_artworks.append(artwork_detail)

            # Display full details
            description = artwork_detail.get("description", "No description available")
            print(f"  Description: {description[:120]}{'...' if len(description) > 120 else ''}")

            # Display metadata
            metadata = artwork_detail.get("metadata", {})
            if metadata:
                artist = metadata.get("artist", "Unknown")
                dimensions = metadata.get("dimensions", "Unknown")
                f_number = metadata.get("f-number", "N/A")
                print(f"  Artist: {artist}")
                if dimensions:
                    print(f"  Dimensions: {dimensions}")
                if f_number != "N/A":
                    print(f"  F-Number: {f_number}")

            # Display tags if available
            tags = artwork_detail.get("tags", [])
            if tags:
                print(f"  Tags: {', '.join(tags)}")

            # Display image information
            images = artwork_detail.get("images", [])
            if images:
                image = images[0]
                thumbnail_url = image.get("thumbnail", "N/A")
                medium_url = image.get("medium", "N/A")
                large_url = image.get("large", "N/A")
                print(f"  Image resolutions available:")
                print(f"    - Thumbnail: {thumbnail_url[:50]}...")
                print(f"    - Medium: {medium_url[:50]}...")
                print(f"    - Large: {large_url[:50]}...")

        except Exception as e:
            print(f"  ✗ Error fetching details: {e}")

        print()

    # Step 4: Demonstrate pagination for larger result sets
    if total_count > 3:
        print("[STEP 3] Demonstrating pagination...")
        try:
            next_page_results = client.search_artworks(query=search_term, offset=3)
            next_page_data = next_page_results.get("data", {})
            next_items = next_page_data.get("items", [])
            next_offset = next_page_data.get("offset", 3)

            if next_items:
                print(f"✓ Retrieved next page (offset={next_offset})")
                print(f"  Results {next_offset + 1}-{next_offset + len(next_items)} of {total_count}:")
                for item in next_items[:2]:
                    title = item.get("title", "Unknown")
                    print(f"    - {title}")
            else:
                print("  No more results available")
        except Exception as e:
            print(f"✗ Error fetching next page: {e}")

    # Step 5: Browse full collection without search
    print("\n[STEP 4] Browsing full collection (first page)...")
    try:
        collection_results = client.get_collection(offset=0)
        collection_data = collection_results.get("data", {})
        all_items = collection_data.get("items", [])
        collection_count = collection_data.get("count", 0)

        print(f"✓ Total items in collection: {collection_count}")
        print(f"  Showing first {min(2, len(all_items))} items:")
        for item in all_items[:2]:
            title = item.get("title", "Unknown")
            item_id = item.get("id", "Unknown")
            print(f"    - {title} (ID: {item_id})")
    except Exception as e:
        print(f"✗ Error browsing collection: {e}")

    # Step 6: Summary
    print("\n" + "=" * 80)
    print(f"SUMMARY: Successfully retrieved detailed information for {len(detailed_artworks)} artwork(s)")
    print("=" * 80)


if __name__ == "__main__":
    main()