External API Endpoints Documented

External API Endpoints

This document describes all external API endpoints used by the reconciliation service strategies.

Open Library API

Base URL: https://openlibrary.org

File: lib/strategies_openlibrary.py

Search Endpoint

• URL: /search.json
• Method: GET
• Purpose: Search for books by title and author
• Parameters:

  Parameter	Type	Description
  title	string	Book title to search
  author	string	Author name to search
  limit	string	Maximum number of results (default: '50')

• Function: _search_title()

Work Data Endpoint

• URL: /works/{work_key}.json
• Method: GET
• Purpose: Fetch detailed work data for a specific work
• Parameters: None (work_key is part of the path)
• Function: extend_data()

Editions Endpoint

• URL: /works/{work_key}/editions.json
• Method: GET
• Purpose: Fetch all editions for a work (ISBNs, publishers, OCLC numbers, etc.)
• Parameters: None (work_key is part of the path)
• Function: extend_data()

---

Google Books API

Base URL: https://www.googleapis.com/books/v1

File: lib/strategies_google_books.py

Volumes Search Endpoint

• URL: /volumes
• Method: GET
• Purpose: Search for books
• Parameters:

  Parameter	Type	Description
  q	string	Query string with intitle: and inauthor: prefixes
  projection	string	Data projection level
  maxResults	integer	Maximum number of results

• Function: _search_google_books()

Volume Details Endpoint

• URL: /volumes/{volume_id}
• Method: GET
• Purpose: Retrieve specific volume details
• Parameters: None (volume_id is part of the path)
• Function: _parse_single_results()

---

VIAF (Virtual International Authority File) API

Base URL: https://viaf.org

File: lib/strategies_viaf.py, lib/strategies_helpers.py

Search Endpoint

• URL: /api/search
• Method: POST (JSON body)
• Purpose: Search for names and titles
• Request Body:

  {
    "reqValues": {
      "field": "local.localID",
      "index": "local.localID",
      "searchTerms": "search query"
    },
    "meta": {
      "env": "live",
      "pageIndex": 1,
      "pageSize": 100
    }
  }

• Functions: _search_name(), _search_title()

Cluster RDF Endpoint

• URL: /{viaf_id}/rdf.xml or /viaf/{viaf_id}/rdf.xml
• Method: GET
• Purpose: Download cluster RDF data for a VIAF record
• Parameters: None (viaf_id is part of the path)
• Function: _download_viaf_cluster_rdf()

---

OCLC WorldCat Discovery API

Base URL: https://americas.discovery.api.oclc.org/worldcat/search/v2

File: lib/strategies_oclc.py

OAuth Token Endpoint

• URL: https://oauth.oclc.org/token
• Method: POST
• Purpose: Obtain OAuth2 access token
• Parameters:

  Parameter	Type	Description
  grant_type	string	Always 'client_credentials'
  scope	string	API scope

• Authentication: Basic Auth with client_id and client_secret
• Function: get_access_token()

Bibliographic Search Endpoint

• URL: /bibs
• Method: GET
• Purpose: Search WorldCat bibliographic records
• Parameters:

  Parameter	Type	Description
  q	string	Search query with au: (author) and ti: (title) prefixes
  limit	integer	Maximum number of results

• Headers: Authorization: Bearer {access_token}
• Functions: _search_worldcat(), _search_title()

---

Library of Congress (ID.LOC.GOV) API

Base URL: https://id.loc.gov

File: lib/strategies_id_loc_gov.py, lib/strategies_helpers.py

Works Suggest Endpoint

• URL: /resources/works/suggest2/
• Method: GET
• Purpose: Search and suggest works
• Parameters:

  Parameter	Type	Description
  q	string	Search query
  searchtype	string	Type of search
  rdftype	string	RDF type filter
  count	integer	Number of results

• Function: _search_id()

Names Suggest Endpoint

• URL: /authorities/names/suggest2/
• Method: GET
• Purpose: Search and suggest name authorities
• Parameters:

  Parameter	Type	Description
  q	string	Search query (LCCN or name)

• Function: _return_lc_suggest2_data()

Instance RDF Endpoint

• URL: /resources/instances/{id}.cbd.rdf
• Method: GET
• Purpose: Retrieve instance RDF data
• Parameters: None (id is part of the path)
• Function: _enrich_id()

---

Wikidata SPARQL API

Base URL: https://query.wikidata.org

File: lib/strategies_wikidata.py, lib/strategies_helpers.py

SPARQL Endpoint

• URL: /sparql
• Method: GET
• Purpose: Execute SPARQL queries against Wikidata
• Parameters:

  Parameter	Type	Description
  query	string	SPARQL query string
  format	string	Response format (default: 'json')

• Functions: _search_title(), _return_wikidata_value()

---

HathiTrust APIs

Files: lib/strategies_hathitrust.py, lib/strategies_hathitrust_build_db.py

File List Endpoint

• URL: https://www.hathitrust.org/files/hathifiles/hathi_file_list.json
• Method: GET
• Purpose: Get list of available HathiTrust dump files for download
• Parameters: None
• Function: find_dump_url()

Catalog Record URL (for linking)

• URL: https://catalog.hathitrust.org/Record/{ht_bib_key}
• Purpose: Direct link to HathiTrust catalog records
• Usage: Building result URIs in _parse_results()

Cover Image Endpoint

• URL: https://babel.hathitrust.org/cgi/imgsrv/cover
• Method: GET
• Purpose: Retrieve cover images for records
• Parameters:

  Parameter	Type	Description
  id	string	HathiTrust identifier
  width	integer	Image width

• Function: Used in extend_data() for thumbnails

---

WorldCat Direct Links

Base URL: http://www.worldcat.org

OCLC Record URL (for linking)

• URL: /oclc/{oclc_number}
• Purpose: Direct link to WorldCat records
• Usage: Building result URIs in OCLC strategy

---

Summary Table

API Service	Base URL	Auth Required	Primary Use
Open Library	https://openlibrary.org	No	Book search & metadata
Google Books	https://www.googleapis.com/books/v1	API Key (optional)	Book search
VIAF	https://viaf.org	No	Authority data
OCLC WorldCat	https://americas.discovery.api.oclc.org	OAuth2	Bibliographic search
Library of Congress	https://id.loc.gov	No	Authority & work data
Wikidata	https://query.wikidata.org	No	SPARQL queries
HathiTrust	https://www.hathitrust.org	No	Dump files & records