OpenSFHistory APIopensfhistory.org ↗

"""
OpenSFHistory Mapped Images API Client

Access historical San Francisco images with geographic locations and metadata.
Get your API key from: https://parse.bot/settings
"""

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


class ParseClient:
    """Client for the OpenSFHistory Mapped Images API."""

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

        Args:
            api_key: API key for authentication. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "a27c5d27-17a2-455c-aaf2-cce506f24093"
        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 environment variable not set")

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

        Args:
            endpoint: The endpoint name to call.
            method: HTTP method (GET or POST).
            **params: Query/body parameters.

        Returns:
            The JSON response from the API.

        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_mapped_images(
        self,
        page: int = 1,
        limit: int = 50,
        min_lat: Optional[float] = None,
        max_lat: Optional[float] = None,
        min_lng: Optional[float] = None,
        max_lng: Optional[float] = None
    ) -> Dict[str, Any]:
        """
        Get paginated list of all mapped historical images with geographic coordinates.

        Args:
            page: Page number for pagination (default 1).
            limit: Number of results per page, between 1-200 (default 50).
            min_lat: Minimum latitude for bounding box filter.
            max_lat: Maximum latitude for bounding box filter.
            min_lng: Minimum longitude for bounding box filter.
            max_lng: Maximum longitude for bounding box filter.

        Returns:
            Dictionary containing images list and pagination info.
        """
        params = {
            "page": page,
            "limit": limit
        }

        if min_lat is not None:
            params["min_lat"] = min_lat
        if max_lat is not None:
            params["max_lat"] = max_lat
        if min_lng is not None:
            params["min_lng"] = min_lng
        if max_lng is not None:
            params["max_lng"] = max_lng

        return self._call("get_mapped_images", method="GET", **params)

    def get_image_details(self, image_id: str) -> Dict[str, Any]:
        """
        Get detailed metadata for a specific image.

        Args:
            image_id: The image identifier (e.g., 'wnp32.3610.jpg').

        Returns:
            Dictionary containing detailed image metadata.
        """
        return self._call("get_image_details", method="GET", image_id=image_id)

    def get_images_at_location(self, latitude: str, longitude: str) -> Dict[str, Any]:
        """
        Get all images at a specific map coordinate.

        Args:
            latitude: Latitude of the map location as a string.
            longitude: Longitude of the map location as a string.

        Returns:
            Dictionary containing images at the location.
        """
        return self._call("get_images_at_location", method="GET", latitude=latitude, longitude=longitude)


def main():
    """Demonstrate practical usage of the OpenSFHistory API."""
    # Initialize the client
    client = ParseClient()

    print("=" * 70)
    print("OpenSFHistory Mapped Images API - Practical Usage Example")
    print("=" * 70)

    # Step 1: Get mapped images from San Francisco downtown area
    print("\n📍 Step 1: Fetching historical images from San Francisco downtown...")
    print("   (Using bounding box: 37.785°N to 37.795°N, -122.415°W to -122.405°W)")

    response = client.get_mapped_images(
        page=1,
        limit=10,
        min_lat=37.785,
        max_lat=37.795,
        min_lng=-122.415,
        max_lng=-122.405
    )

    images = response.get("images", [])
    total = response.get("total", 0)

    print(f"✓ Found {total} total images in area, showing {len(images)} results:")

    # Step 2: Display summary of found images
    print("\n📷 Images found:")
    for idx, image in enumerate(images[:5], 1):  # Show first 5
        print(f"   {idx}. ID: {image['image_id']}")
        print(f"      Location: {image['latitude']:.6f}, {image['longitude']:.6f}")
        print(f"      URL: {image['image_url']}")

    if len(images) == 0:
        print("   No images found in this area. Trying a different location...")
        # Try a broader area
        response = client.get_mapped_images(page=1, limit=10)
        images = response.get("images", [])
        print(f"   Found {len(images)} images in broader search")

    # Step 3: Get details for the first image
    if images:
        first_image_id = images[0]["image_id"]
        print(f"\n📖 Step 2: Fetching detailed metadata for image: {first_image_id}")

        details = client.get_image_details(first_image_id)

        print("\n✓ Image Details:")
        print(f"   Title: {details.get('title', 'N/A')}")
        print(f"   Date: {details.get('date', 'N/A')}")
        print(f"   Photographer: {details.get('photographer', 'N/A')}")
        print(f"   Collection: {details.get('collection', 'N/A')}")
        print(f"   Description: {details.get('description', 'N/A')[:100]}...")
        print(f"   Display URL: {details.get('display_url', 'N/A')}")

        # Step 4: Get all images at the same location
        print(f"\n🗺️  Step 3: Finding all images at location ({images[0]['latitude']}, {images[0]['longitude']})...")

        location_images = client.get_images_at_location(
            latitude=str(images[0]["latitude"]),
            longitude=str(images[0]["longitude"])
        )

        location_count = location_images.get("count", 0)
        location_results = location_images.get("images", [])

        print(f"✓ Found {location_count} image(s) at this exact location:")
        for img in location_results:
            print(f"   - {img['image_id']}: {img['title'][:60]}...")

    # Step 5: Show pagination capability
    print(f"\n📄 Step 4: Demonstrating pagination (getting page 2)...")
    page_2 = client.get_mapped_images(page=2, limit=5)
    print(f"✓ Page 2 results: {len(page_2.get('images', []))} images")
    print(f"  Total pages available: {page_2.get('total_pages', 'N/A')}")

    print("\n" + "=" * 70)
    print("✅ API demonstration complete!")
    print("=" * 70)


if __name__ == "__main__":
    main()