University of Michigan Library Catalog Skill

Search U-M Library's catalog (Alma) for print and online holdings. No API key needed.

Overview

U-M runs its catalog on Ex Libris Alma. Alma has a public SRU interface (Search/Retrieve via URL, a library standard for searching catalogs over plain HTTP). Queries are written in CQL (Contextual Query Language, e.g. alma.title="明史"). Records come back as MARCXML.

https://umich.alma.exlibrisgroup.com/view/sru/01UMICH_INST
  ?version=1.2&operation=searchRetrieve&recordSchema=marcxml
  &query=alma.title="明史"&maximumRecords=10

Critical: Things Claude Won't Know Without This Skill

Do not use Library Search (search.lib.umich.edu) or the Spectrum MCP

U-M's public search site and its backend API (search.lib.umich.edu/spectrum/...) sit behind a Cloudflare bot check. Scripts get HTTP 403 with a "Just a moment…" page. The mlibrary/spectrum repo has an MCP server, but it only runs inside U-M. Use Alma SRU instead. Use search.lib.umich.edu/catalog/record/{mms_id} only as a link for people to open in a browser.

Holdings are in the AVA and AVE fields

Each MARC record includes Alma availability fields:

• AVA = print/physical copy. $q library name, $c location, $d call number, $e available/unavailable, $f item count, $t volume summary.
• AVE = online copy. $m collection, $t interface (platform), $e Available, $u access link (when the library supplies one).

The script reads both into holdings.physical and holdings.electronic. Keys: holdings.physical[] has library, location, call_number, availability, items_total, items_unavailable, summary; holdings.electronic[] has collection, interface, availability, note, url.

Chinese/Japanese/Korean script is in 880 fields

Like most US catalogs, the main fields (245 title, 100 author, 260/264 publisher) are romanized (pinyin, Hepburn, McCune-Reischauer). The original script is in a linked 880 field. The script pairs them, so title reads 八史經籍志 (Ba shi jing ji zhi).

You can search in either script. alma.title="明史" and alma.title="Ming shi" both work but return different sets, so try both for full coverage.

Title searches match words, not phrases

• alma.title="shi dian" matches records with shi and dian anywhere in the title (353 hits at U-M, including a Shenyang phone book). Quotes and adj change nothing; == matches the whole title field exactly.
• Use phrase=True (CLI --phrase) to keep only titles that contain the term as one connected phrase. It filters each page after the search, so total is still the server's count; use search_all(..., phrase=True) to scan every page.
• Pinyin syllables stay ambiguous: shi dian also matches 知识典籍 (zhi shi dian ji), and ji qi is 機器 as well as 祭器. After a romanized search, keep the records whose vernacular title has the characters you want.
• A CJK title search can also miss titles that contain the term. Alma splits CJK titles into words with a dictionary: 文廟祀典考 is indexed as 文 / 廟祀 / 典考, so alma.title="文廟" misses it at U-M and Princeton (Yale finds it). The romanized Wen miao finds it.
• So never treat one CJK title search as complete. Search the traditional, simplified, and romanized forms (文廟, 文庙, Wen miao) and merge the results by mms_id.

Limits and quirks

• 50 records per request at most (maximumRecords). Page with startRecord (1-based).
• Sort goes inside the CQL, not in a separate parameter: ... sortBy alma.main_pub_date/sort.descending. The sortKeys parameter is ignored. Sortable: title, creator, main_pub_date. Records with unknown dates (uuuu) sort first in ascending order; add cql="alma.main_pub_date>=1000" to drop them. But placeholder years such as #### still pass that filter and sort first (seen at Princeton and U-M on 2026-10-26). Add known_dates=True (CLI --known-dates) to drop records whose year is not four digits. It filters each page after the search, like phrase.
• Subject headings: write LCSH as plain words, without --, in LC's inverted form. alma.subjects="Confucius Cult" works; "Confucius -- Cult" gives 0. "Temples, Confucian" works; "Confucian temples" gives 0.
• Subject heading output: name and title subjects (600/610/611/630) keep their dates and title in the heading, e.g. Song, Yingxing, 1587-approximately 1666. Dian gong kai wu. Only the subdivisions $v $x $y $z are joined with --, e.g. Science -- China -- History.
• Network errors are retried. Dropped connections, read timeouts, and HTTP 429/5xx are retried up to 4 times (waiting 5, 10, 20 s, or Retry-After). If a later page of search_all() still fails, it raises IncompleteResults; the records fetched so far are in its .records.
• Unknown index names fail with a vague "Catalog search has encountered an error". Check the spelling against references/api_reference.md.
• Encode the query with normal URL encoding (urllib.parse.quote). Raw Chinese or quotes in the URL give HTTP 400.
• Truncation: alma.lc_class_number=DS753* (no quotes around the term).

When to Use

• "Does Michigan have X?" / "Where is X shelved at U-M?"
• Finding Chinese, Japanese, or Korean books at the U-M Asia Library
• Finding rare or pre-modern editions (e.g. Ming/Qing imprints, microfilm in FILM CS ...)
• Getting MARC data (OCLC, LCCN, ISBN, subjects) for a known item
• Comparing holdings across Harvard, Columbia, LOC, and U-M

Quick Start

CLI

# Title search in Chinese, Chinese-language only, oldest first
python scripts/umich_api.py search --title 明史 --language chi --sort date_asc --limit 5

# Author search
python scripts/umich_api.py search --author "Brook, Timothy" --limit 10

# Raw CQL: pre-1700 imprints with 明史 in the title
python scripts/umich_api.py search --cql 'alma.title=明史 and alma.main_pub_date<1700'

# Call number range, JSON output
python scripts/umich_api.py search --call-number 'DS753*' --json

# One record by MMS ID; --raw for all MARC fields
python scripts/umich_api.py record 990023071550106381
python scripts/umich_api.py record 990023071550106381 --raw

Python

from scripts.umich_api import UMichCatalogAPI

um = UMichCatalogAPI()

result = um.search(title="明史", language="chi", sort="date_asc", limit=10)
print(result["total"])
for rec in result["records"]:
    print(rec["title"], rec["year"])
    for h in rec["holdings"]["physical"]:
        print("  ", h["library"], h["call_number"], h["availability"])

# Combine fields (AND) or add raw CQL
um.search(author="王守仁", subject="Philosophy, Chinese")
um.search(cql="alma.main_pub_date>=1600 and alma.main_pub_date<1700", keyword="王陽明")

# Identifier lookups
um.search(isbn="9787101003277")
um.search(oclc="424023")

# More than 50 results
records = um.search_all(subject="China History Ming dynasty", max_results=200)

# Single record
rec = um.get_record("990023071550106381")
marc = um.get_record("990023071550106381", raw=True)  # full MARC fields

Search field names: keyword, title, author, subject, isbn, issn, oclc, lccn, publisher, series, call_number, language (MARC code: chi, jpn, kor, eng), mms_id. Sort: date_desc, date_asc, title, author.

Summary record shape

{
  "mms_id": "990023071550106381",
  "title": "八史經籍志 (Ba shi jing ji zhi)",
  "titles": [{"romanized": "Ba shi jing ji zhi", "vernacular": "八史經籍志"}],
  "author": "",
  "publication": "[蘇州] : [振新印書社], 光緖8年 [1882] ([Suzhou] : ...)",
  "year": "1882",
  "language": "chi",
  "subjects": ["..."],
  "isbns": [], "oclc": ["..."], "lccn": [],
  "lc_call_number": "Z3102 .P15",
  "classifications": [{"scheme": "lcc", "number": "Z3102 .P15"}],
  "subject_headings": [{"heading": "Chinese literature -- Bibliography", "source": "lcsh", "tag": "650"}],
  "holdings": {
    "physical": [{"library": "Buhr Shelving Facility", "location": "Main",
                  "call_number": "Z 3102 .P15", "availability": "available",
                  "items_total": "2", "items_unavailable": "0", "summary": "(v.1-16 1883)"}],
    "electronic": []
  },
  "url": "https://search.lib.umich.edu/catalog/record/990023071550106381"
}

Cataloging fields (for comparing cataloging traditions): subject_headings lists each 6XX heading with its vocabulary (lcsh, csht = Taiwan's Chinese subject headings, fast, mesh, …), and classifications lists each class number with its scheme (lcc, ddc, ncsclt = 中文圖書分類法, the Chinese classification used in Taiwan, …). subjects stays a plain list of strings.

Best Practices

1. Search both scripts. Run the Chinese-script and the romanized form of a title; records differ in how fully they are romanized or linked.
2. Narrow with language (chi, jpn, kor) when a title word is common in many languages.
3. Use oclc or isbn to match an item found in another catalog. These are exact.
4. Give people the url so they can see live circulation status, request items, or check "Get This" options in a browser.
5. Respect the server. The script waits 1 second between requests and backs off on HTTP 429/503 with Retry-After. Do not loop over thousands of pages.

Related Skills

• alma-sru-catalogs: search this library and 20 others (Oxford, Cambridge, Toronto, Berkeley, …) in one call
• princeton-library-catalog, yale-library-catalog, pitt-library-catalog: the same Alma SRU method at other libraries
• hathitrust-catalog: U-M is HathiTrust's founding partner. Use OCLC numbers from here to find digitized copies.
• harvard-library-catalog, loc-catalog: compare holdings across libraries
• zotero-local: save found records into Zotero
• cbdb-local: identify authors of Chinese works

Resources

• references/api_reference.md — SRU parameters, CQL syntax, index list, MARC and AVA/AVE field guide
• scripts/umich_api.py — Python client and CLI (zero dependencies)
• tests/test_umich_api.py — offline tests (python -m unittest discover -s tests)
• Ex Libris SRU docs: https://developers.exlibrisgroup.com/alma/integrations/sru/

Feedback and Citation

Report a problem. This skill is part of the public repository kltng/humanities-skills. If it fails (an API changed, a script errors, or these instructions are wrong), report it as a GitHub issue:

1. Ask the user before filing. Issues are public.
2. Check for an existing report: gh issue list --repo kltng/humanities-skills --state all --search "umich-library-catalog"
3. File it: gh issue create --repo kltng/humanities-skills --label bug --title "[umich-library-catalog] <short summary>" --body "<details>". Without gh, give the user this link: https://github.com/kltng/humanities-skills/issues/new?template=skill-problem.yml
4. Include the skill name and version, what you ran, the error text, what you expected, and the environment (OS, Python version). Leave out API keys, personal data, private file paths, and unpublished research.

Cite. If this skill helped work that is published, please cite it, together with the data source it uses:

Tang, Kwok-leong. humanities-skills: umich-library-catalog (version <version at the top of this file>). GitHub, <year>. https://github.com/kltng/humanities-skills

When you help a user write up results that relied on this skill, remind them once about this citation.