David Rumsey APIdavidrumsey.com ↗

"""
David Rumsey Map Collection API Client

Search and retrieve detailed metadata from the David Rumsey Historical Map Collection.
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional


class ParseClient:
    """Client for David Rumsey Map Collection API"""

    def __init__(self, api_key: Optional[str] = None):
        """Initialize the Parse API client"""
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "e62c82ea-9333-413b-9115-6db7e68e5acf"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        if not self.api_key:
            raise ValueError("API key must be provided or set in PARSE_API_KEY environment variable")

    def _call(self, endpoint: str, method: str = "POST", **params) -> dict:
        """Make an API call to the Parse endpoint"""
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }

        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method == "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 search_maps(
        self,
        keyword: str = "San Francisco",
        page: int = 1,
        page_size: int = 20
    ) -> dict:
        """
        Search the David Rumsey Historical Map Collection by keyword.

        Args:
            keyword: Search keyword to query the map collection
            page: Page number for pagination (starts at 1)
            page_size: Number of results per page (1-100)

        Returns:
            Dictionary containing total_results, page, page_size, and results array
        """
        return self._call(
            "search_maps",
            method="GET",
            keyword=keyword,
            page=page,
            page_size=page_size
        )

    def get_map_details(self, item_id: str) -> dict:
        """
        Get detailed metadata for a specific map item by its unique ID.

        Args:
            item_id: Unique item identifier in format RUMSEY~8~1~XXXXXX~XXXXXXXX

        Returns:
            Dictionary containing comprehensive map metadata including IIIF URLs
        """
        return self._call("get_map_details", method="GET", item_id=item_id)


def main():
    """Practical workflow example: search for maps and get details on georeferenced ones"""

    client = ParseClient()

    print("=" * 60)
    print("David Rumsey Map Collection - Search and Details Example")
    print("=" * 60)

    # Step 1: Search for maps about California
    print("\n1. Searching for maps about 'California Gold Rush'...")
    search_results = client.search_maps(
        keyword="California Gold Rush",
        page=1,
        page_size=5
    )

    print(f"   Found {search_results['total_results']} total maps")
    print(f"   Showing {len(search_results['results'])} results on page {search_results['page']}\n")

    # Step 2: Process each search result
    georeferenced_count = 0
    maps_to_examine = []

    for idx, map_item in enumerate(search_results['results'], 1):
        print(f"\n   Result {idx}: {map_item['title']}")
        print(f"   - Date: {map_item['date']}")
        print(f"   - Author: {map_item['author']}")
        print(f"   - Type: {map_item['type']}")
        print(f"   - Image Size: {map_item['image_width']}x{map_item['image_height']}")
        print(f"   - Georeferenced: {map_item['georeferenced']}")

        if map_item['georeferenced']:
            georeferenced_count += 1
            maps_to_examine.append(map_item['item_id'])

    print(f"\n2. Found {georeferenced_count} georeferenced maps from search results")

    # Step 3: Get detailed information for georeferenced maps
    if maps_to_examine:
        print("\n3. Fetching detailed information for georeferenced maps...\n")

        for item_id in maps_to_examine[:3]:  # Limit to first 3 for demo
            print(f"   Fetching details for: {item_id}")
            details = client.get_map_details(item_id)

            print(f"   Full Title: {details['full_title']}")
            if details.get('obj_width_cm') and details.get('obj_height_cm'):
                print(f"   Physical Size: {details['obj_width_cm']}cm × {details['obj_height_cm']}cm")
            if details.get('scale'):
                print(f"   Scale: {details['scale']}")
            print(f"   IIIF Manifest: {details['iiif_manifest_url']}")
            print(f"   Full Resolution: {details['full_resolution_image_url']}")
            print(f"   Status: {details['georeferencer_status']}")
            print()

    print("=" * 60)
    print("Example workflow completed successfully!")
    print("=" * 60)


if __name__ == "__main__":
    main()