harvard-library-catalog

# Harvard Library API Skill Search and retrieve bibliographic records from Harvard Library's catalog of 13M+ items. ## Critical: Things Claude Won't Know Without This Skill ### LibraryCloud field-based search uses query parameters, NOT Solr syntax The Item API uses **field names as query parameters** — not `q=field:value` Solr syntax. ``` CORRECT: https://api.lib.harvard.edu/v2/items.json?title=hamlet&name=shakespeare WRONG: https://api.lib.harvard.edu/v2/items?q=title:hamlet ``` The `q=` parameter is for **keyword search across all fields**. Field-specific search uses dedicated parameters like `title=`, `name=`, `subject=`, `identifier=`, etc. ### JSON requires `.json` in the URL path Responses are XML by default. To get JSON, append `.json` before the query string: ``` JSON: https://api.lib.harvard.edu/v2/items.json?title=hamlet Dublin Core: https://api.lib.harvard.edu/v2/items.dc.json?title=hamlet Default XML: https://api.lib.harvard.edu/v2/items?title=hamlet ``` ### PRESTO is for direct record lookup by HOLLIS ID PRESTO returns raw MARC, MODS, or Dublin Core for a single record by its HOLLIS number. It complements LibraryCloud when you need the original catalog record: ``` MARC: https://webservices.lib.harvard.edu/rest/marc/hollis/{HOLLIS_ID} MODS: https://webservices.lib.harvard.edu/rest/mods/hollis/{HOLLIS_ID} DC: https://webservices.lib.harvard.edu/rest/dc/hollis/{HOLLIS_ID} ``` PRESTO returns XML only and does not support JSON serialization. ISBN/barcode lookups may not work on all records. ### User-Agent header is required LibraryCloud returns 403 without a User-Agent header. Always include one: ```bash curl -H 'User-Agent: MyApp/1.0' 'https://api.lib.harvard.edu/v2/items.json?title=hamlet' ``` The Python script includes this automatically. ### Rate limit: max 1 request/second, 300 per 5 minutes Exceeding this triggers a 5-minute lockout. The Python script handles this automatically. ## Choosing an Access Method | Need | Method | |------|--------| | Search by title, author, subject, date | LibraryCloud Item API (field params) | | Full-text keyword search | LibraryCloud Item API (`q=` param) | | Look up by ISBN, LCCN, or other identifier | LibraryCloud `identifier=` or `q=` keyword | | Browse digital collections | LibraryCloud `collectionTitle=` or Collections API | | Get raw MARC record for a known HOLLIS ID | PRESTO `/rest/marc/hollis/{id}` | | Faceted browsing (by language, date, genre) | LibraryCloud `facets=` parameter | ## Typical Workflow: Book Title to Full Bibliography This is the primary use case — an LLM extracts a book title from a document and needs complete bibliographic data: ```python from scripts.harvard_api import HarvardLibraryAPI api = HarvardLibraryAPI() # 1. Search by title (and optionally author) results = api.search(title="The Great Gatsby", name="Fitzgerald") # 2. Get the first match's summary if results: summary = api.summarize(results[0]) # → title, author, publisher, date, ISBN, subjects, language, physical description # 3. For deeper data, get MARC via PRESTO hollis_id = api.get_record_id(results[0]) if hollis_id: marc = api.get_presto_record(hollis_id, format="mods") ``` ## Key Search Fields | Field | What it searches | Exact match? | |-------|-----------------|-------------| | `q` | All fields (keyword) | No | | `title` | Title, subtitle, part name/number | Yes (`title_exact`) | | `name` | All name fields (author, editor, etc.) | No | | `subject` | All subject fields (topic, geographic, temporal) | Yes (`subject_exact`) | | `identifier` | ISBN, LCCN, other system IDs | Yes | | `languageCode` | ISO language code (e.g., `chi`, `eng`) | Yes | | `dateIssued` | Publication date (YYYY) | Yes | | `dates.start` / `dates.end` | Date range filter | — | | `genre` | Genre/form (e.g., "Drawings", "Maps") | Yes (`genre_exact`) | | `repository` | Harvard library name | Yes | | `isOnline` | Has digital version (`true`/`false`) | — | | `recordIdentifier` | HOLLIS/Alma record ID | Yes | Combine fields freely: `?title=hamlet&name=shakespeare&languageCode=ger&dates.start=1900` ## Pagination - `limit=N` (default 10, max 250) - `start=N` for offset-based pagination (up to ~30K results) - `cursor=*` then `cursor={nextCursor}` for large result sets (up to 100K) ## Facets Add `facets=field1,field2` to get value counts. Useful fields: `name`, `subject`, `languageCode`, `genre`, `resourceType`, `repository`, `dateIssued`. ``` ?title=china&facets=languageCode,genre ``` ## Python Script Use `scripts/harvard_api.py` for programmatic access (zero dependencies): ```python from scripts.harvard_api import HarvardLibraryAPI api = HarvardLibraryAPI() # Keyword search results = api.search(q="Chinese porcelain Ming dynasty") # Field search results = api.search(title="dream of the red chamber", languageCode="chi") # With facets results, facets = api.search_with_facets(subject="astronomy", facets=["genre", "dateIssued"]) # Pagination all_results = api.search_all(title="peanuts", name="schulz", max_results=500) # PRESTO lookup marc_xml = api.get_presto_record("011557057", format="marc") # Summarize a record for r in results[:5]: print(api.summarize(r)) ``` ## API Endpoints | Endpoint | URL | |----------|-----| | LibraryCloud Items | `https://api.lib.harvard.edu/v2/items` | | LibraryCloud Collections | `https://api.lib.harvard.edu/v2/collections` | | PRESTO (MARC/MODS/DC) | `https://webservices.lib.harvard.edu/rest/{format}/hollis/{id}` | ## Related Skills - **wikidata-search**: Cross-reference Harvard catalog entries with Wikidata for external identifiers (VIAF, LoC, etc.) - **cbdb-api**: Look up authors of Chinese historical texts in CBDB for biographical context ## Resources - `references/api_reference.md` — Complete field reference with all searchable fields, facets, and query examples - `scripts/harvard_api.py` — Full-featured Python client with rate limiting, pagination, and record summarization