hathitrust-catalog

# HathiTrust Bibliographic API Skill Look up records and digitized volumes in HathiTrust's collection of 17M+ volumes from major research libraries. ## Critical: Things Claude Won't Know Without This Skill ### This is a lookup API, NOT a search API HathiTrust's Bibliographic API retrieves records by **known identifiers** only. There is no keyword or title search. You must have an ISBN, OCLC number, LCCN, ISSN, or HathiTrust ID. ``` WORKS: https://catalog.hathitrust.org/api/volumes/brief/isbn/0140449264.json NOT POSSIBLE: https://catalog.hathitrust.org/api/volumes/brief/search?q=hamlet ``` If you only have a title/author, search another catalog first (LibraryCloud, Library of Congress) to get an ISBN or OCLC number, then look it up here. ### Two endpoint variants: brief vs full | Endpoint | Returns | Use when | |----------|---------|----------| | `/api/volumes/brief/` | Metadata + items (no MARC) | You just need titles, ISBNs, holdings, digital access links | | `/api/volumes/full/` | Same + complete MARC-XML | You need full cataloging data | ### Empty results are not errors When no record matches, the API returns `{"records": {}, "items": []}` with HTTP 200 — not a 404. Always check if `records` is empty. ### Batch up to 20 lookups in one request Use the multi-ID endpoint to batch lookups: ``` /api/volumes/brief/json/isbn:0140449264|oclc:228668653 ``` Pipe-separated as `type:value`. Max 20 per request. ## Identifier Types | Type | Example | Notes | |------|---------|-------| | `isbn` | `0140449264` or `9780140449266` | ISBN-10 or ISBN-13, digits only (+ trailing X) | | `oclc` | `228668653` | OCLC number, digits only | | `lccn` | `72081773` | URL-encode spaces/slashes | | `issn` | `03785955` | Digits only | | `htid` | `mdp.39015058510069` | HathiTrust volume ID | | `recordnumber` | `000578050` | 9-digit HathiTrust record number | ## Response Structure ```json { "records": { "009058846": { "recordURL": "https://catalog.hathitrust.org/Record/009058846", "titles": ["The Odyssey / Homer ; translated by Robert Fagles."], "isbns": ["0140268863", "9780140268867"], "oclcs": ["34228839"], "lccns": ["96017900"], "publishDates": ["1997"] } }, "items": [ { "orig": "University of Michigan", "htid": "mdp.39015042182054", "itemURL": "https://babel.hathitrust.org/cgi/pt?id=mdp.39015042182054", "rightsCode": "ic", "usRightsString": "Limited (search-only)", "lastUpdate": "20240115", "enumcron": false } ] } ``` Key fields: - **`rightsCode`**: `pd` = public domain (full text available), `ic` = in-copyright (search only) - **`usRightsString`**: `"Full View"` or `"Limited (search-only)"` - **`itemURL`**: Direct link to the HathiTrust page-turner viewer - **`enumcron`**: Volume/issue info (e.g., `"vol. 3"`) or `false` ## Python Script Use `scripts/hathitrust_api.py` for programmatic access (zero dependencies): ```python from scripts.hathitrust_api import HathiTrustAPI ht = HathiTrustAPI() # Single lookup record = ht.lookup_isbn("0140449264") # Multiple identifiers at once results = ht.batch_lookup([ ("isbn", "0140449264"), ("oclc", "228668653"), ("lccn", "96017900"), ]) # Get full MARC-XML record = ht.lookup_isbn("0140449264", full=True) marc = ht.get_marc_xml(record) # Check if digitized and accessible for item in ht.get_items(record): print(f"{item['orig']}: {item['usRightsString']} — {item['itemURL']}") # Summarize print(ht.summarize(record)) ``` ## Typical Workflow: Cross-Reference with Other Catalogs ```python # 1. Search Harvard for a title from harvard_api import HarvardLibraryAPI harvard = HarvardLibraryAPI() results = harvard.search(title="dream of the red chamber") isbn = harvard.get_identifiers(results[0]).get("isbn") # 2. Check HathiTrust for digital version from hathitrust_api import HathiTrustAPI ht = HathiTrustAPI() record = ht.lookup_isbn(isbn) if record and ht.has_full_view(record): print("Full text available:", ht.get_items(record)[0]["itemURL"]) ``` ## API Etiquette - No authentication required - No documented rate limit, but the API is meant for small-batch lookups (not bulk harvesting) - Use HathiFiles or OAI-PMH for bulk data - CORS is fully enabled (`access-control-allow-origin: *`) ## Related Skills - **harvard-library-catalog**: Search Harvard's catalog to find ISBNs/identifiers, then check HathiTrust for digital versions - **wikidata-search**: Cross-reference Wikidata identifiers (P243 = OCLC) with HathiTrust holdings ## Resources - `references/api_reference.md` — Complete API spec with all identifier types and response fields - `scripts/hathitrust_api.py` — Python client with batch lookups, MARC extraction, and access checking