Loc APIloc.gov ↗

"""
Library of Congress Sanborn Maps API Client
Get your API key from: https://parse.bot/settings
"""

import os
import requests
from typing import Optional


class ParseClient:
    """Client for interacting with the Library of Congress Sanborn Maps API through Parse."""

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

        Args:
            api_key: API key for Parse. If not provided, reads from PARSE_API_KEY env var.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "5bef1205-8db9-4d82-a034-aef5571a537e"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")

        if not self.api_key:
            raise ValueError(
                "API key not provided. Set PARSE_API_KEY environment variable or pass api_key parameter."
            )

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

        Args:
            endpoint: The endpoint name to call.
            method: HTTP method to use (GET or POST).
            **params: Parameters to pass to the endpoint.

        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 list_sanborn_sheets(
        self,
        location: str = "san francisco",
        state: str = "california",
        page: int = 1,
        per_page: int = 100,
    ) -> dict:
        """List Sanborn fire insurance map sheets filtered by location.

        Args:
            location: City name to filter maps by (e.g. 'san francisco', 'boston', 'new york').
            state: State name to filter maps by (e.g. 'california', 'massachusetts').
            page: Page number for pagination (default: 1).
            per_page: Number of results per page, between 1 and 150 (default: 100).

        Returns:
            Dictionary containing sheets, total count, and pagination info.
        """
        return self._call(
            "list_sanborn_sheets",
            method="GET",
            location=location,
            state=state,
            page=page,
            per_page=per_page,
        )


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

    print("=" * 80)
    print("Library of Congress Sanborn Maps API - Practical Usage Example")
    print("=" * 80)

    # 1. Search for Sanborn maps in San Francisco, California
    print("\n📍 Fetching Sanborn Fire Insurance Maps for San Francisco, California...")
    response = client.list_sanborn_sheets(
        location="san francisco", state="california", page=1, per_page=10
    )

    print(f"\nFound {response['total']} total maps for San Francisco, CA")
    print(f"Showing page {response['page']} of {response['pages']} (10 results per page)")

    # 2. Process and display the map sheets
    print("\n" + "-" * 80)
    print("Map Sheets Found:")
    print("-" * 80)

    sheets = response.get("sheets", [])

    for idx, sheet in enumerate(sheets, 1):
        print(f"\n{idx}. {sheet['title']}")
        print(f"   Date: {sheet['date']}")
        print(f"   Item ID: {sheet['item_id']}")
        print(f"   Files: {sheet['number_of_files']}")
        print(f"   Library of Congress URL: {sheet['item_url']}")
        print(f"   High-Resolution Image: {sheet['image_url'][:80]}...")
        print(f"   Resource URL: {sheet['resource_url']}")

    # 3. Demonstrate pagination - fetch next page if available
    if response["page"] < response["pages"]:
        print("\n" + "=" * 80)
        print("📄 Fetching next page of results...")
        next_response = client.list_sanborn_sheets(
            location="san francisco", state="california", page=2, per_page=10
        )

        print(f"\nPage 2 contains {len(next_response['sheets'])} more map sheets")
        if next_response["sheets"]:
            first_sheet = next_response["sheets"][0]
            print(f"First map on page 2: {first_sheet['title']}")
            print(f"Date: {first_sheet['date']}")

    # 4. Search for maps in a different city
    print("\n" + "=" * 80)
    print("🔍 Searching for Sanborn maps in Boston, Massachusetts...")
    boston_response = client.list_sanborn_sheets(
        location="boston", state="massachusetts", page=1, per_page=5
    )

    print(f"Found {boston_response['total']} total maps for Boston, MA")
    print(f"Showing {len(boston_response['sheets'])} results:")

    for sheet in boston_response["sheets"]:
        print(f"  • {sheet['title']} ({sheet['date']})")

    print("\n" + "=" * 80)
    print("✅ Example completed successfully!")
    print("=" * 80)


if __name__ == "__main__":
    main()