Volume API

This API enables some endpoints to support catalog search in libraries.

• Main code: https://github.com/hathitrust/catalog/blob/main/static/api/volumes.php
• Public Documentation: https://www.hathitrust.org/member-libraries/resources-for-librarians/data-resources/bibliographic-api/

The rewrite rules in .htaccess are responsible for mapping api/volumes/... endpoints into static/api/volumes.php?... URLs

There are four variations on Bib API endpoints. The components will be abbreviated as follows:

• b brevity, usually but not always enforced to be in {brief, full}
• t type, the output format, typically json but also {html, inlinehtml, oclcscrape} depending on the variation
  • TODO: volumes.php has no provision to emit html or inlinehtml so the rewrite rules are likely out of date
• qf query field, in {recordid, sysid, oclc, htid, issn, isbn, lccn, umid}
• qv query value, such as mdp.001
• Q which is qf combined with qv, e.g., htid:mdp.001
  • Q may have multiple values for a field, e.g., htid:mdp.001|mdp.002 (treated as an OR?)
  • Q may have multiple fields, e.g., htid:mdp.001;oclc:45678 (treated as an AND? -- check the public docs to confirm this)
  • The exact semantics are not entirely clear from the documentation, and are buried in the code

In order of appearance in .htaccess they are:

• b/t/Q
  • e.g. /api/volumes/full/json/htid:mdp.39015048895836
  • This form can be used to perform more complex queries with Q
  • The public documentation calls this "The multi-id request format"
• b/qf/qv.t
  • e.g. /api/volumes/full/htid/mdp.39015048895836.json
  • The public documentation calls this the "Simple, single-identifier API"
• t/Q
  • implies brevity brief
  • FIXME: warnings in https://catalog.hathitrust.org/api/volumes/htid/mdp.39015004074095.json
• qf/qv.t
  • implies brevity brief
  • FIXME: warnings in https://catalog.hathitrust.org/api/volumes/json/htid:mdp.39015004074095

Valid Query Fields

According to the code (lines 94-106), these fields are supported:

• htid / ht_id - HathiTrust item ID
• oclc - OCLC number
• isbn - ISBN
• issn - ISSN
• lccn - Library of Congress Control Number
• recordnumber / recordid / sysid / umid - Catalog record identifiers

The API requires a q parameter with field:value pairs:

1. Query by HathiTrust ID (htid)

http://catalog.hathitrust.org/static/api/volumes.php?q=htid:mdp.39015012668484&type=json&brevity=full&single=1

2. Query by OCLC Number

https://catalog.hathitrust.org/static/api/volumes.php?q=oclc:7107072&type=json&brevity=full

3. Query by ISBN

http://catalog.hathitrust.org/static/api/volumes.php?q=isbn:9780123456789&type=json&brevity=full

4. Query by Record Number

http://catalog.hathitrust.org/static/api/volumes.php?q=recordnumber:000012345&type=json&brevity=full

5. Query by ISSN

http://catalog.hathitrust.org/static/api/volumes.php?q=issn:1234-5678&type=json&brevity=full

6. Query by LCCN

http://catalog.hathitrust.org/static/api/volumes.php?q=lccn:2001012345&type=json&brevity=full

Multiple Queries (OR logic)

Use | to separate multiple queries: http://catalog.hathitrust.org/static/api/volumes.php?q=oclc:12345678|oclc:87654321&type=json&brevity=full

Output Formats

JSON (default structured output)

http://catalog.hathitrust.org/static/api/volumes.php?q=htid:mdp.39015012668484&type=json&brevity=full

HTML (OCLC scrape format)

http://catalog.hathitrust.org/static/api/volumes.php?q=oclc:123456789&type=oclcscrape&brevity=full

JSONP (with callback)

http://catalog.hathitrust.org/static/api/volumes.php?q=htid:mdp.39015012668484&type=json&callback=myFunction&brevity=full

Optional Parameters

Include Full MARC-XML

http://catalog.hathitrust.org/static/api/volumes.php?q=htid:mdp.39015012668484&type=json&brevity=full

Unwrap Single Results

http://catalog.hathitrust.org/static/api/volumes.php?q=htid:mdp.39015012668484&type=json&single=1&brevity=full

Example with Real HathiTrust ID

• https://catalog.hathitrust.org/static/api/volumes.php?q=htid:hvd.ah6h7u&type=json&brevity=full&single=1 This would return JSON with full MARC-XML for that specific HathiTrust item.

• https://catalog.hathitrust.org/api/volumes/full/oclc/007107072.json

• https://catalog.hathitrust.org/api/volumes/brief/oclc/007107072.json