goldrush

Note: This is alpha software. If you rely on this library you should do so with the understanding that you might find errors in the Gold Rush key that is generated. Lets make it better together!

goldrush is a Python implementation of the Gold Rush match key algorithm for identifying "duplicate" MARC records, or records that appear to be about the same bibliographic item. It provides a function that you pass a MARC record and get back the Gold Rush key as a string. Both pymarc and mrrc records are supported — goldrush is duck-typed and imports neither backend itself, so you use whichever one you already parse records with.

goldrush is a class-for-class port of the canonical, production-verified Java reference implementation, coalliance-matchkey, maintained by the Colorado Alliance of Research Libraries (CoAlliance). It targets algorithm version _v07312026, whose version string is embedded in every generated key (just before the trailing format character) so you can tell which algorithm produced a given key. See docs/CoAlliance_Match_Key.md for the field-by-field specification.

The initial code was found in pymarc_dedupe created by Max Kadel and Jane Sandberg at Princeton University Library. The goldrush module was created because pymarc_dedupe included other functionality that was unrelated to Gold Rush, and pymarc_dedupe was not installable as a module via PyPI.

Usage

First install goldrush together with a MARC backend. goldrush does not depend on either pymarc or mrrc directly, so pick one via an extra:

pip install goldrush[pymarc]     # or: pip install goldrush[mrrc]

Then load a record with your backend and generate a key:

>>> from goldrush import goldrush
>>> from pymarc import MARCReader          # or: from mrrc import MARCReader
>>> record = next(MARCReader(open('marc.dat', 'rb')))
>>> goldrush(record)
'pragmaticprogrammerfromjourneymantomaster___________________________________________________________2000____1__addisa________________________________________hunt_________________v07312026p'

The same call works with an mrrc record — its differential test in tests/test_corpus.py runs the whole corpus through both backends and confirms byte-identical keys.

The CoAlliance indexer optionally uses the MARC filename as a hint when deciding whether a record is electronic or print. To match that behaviour, pass the filename:

>>> goldrush(record, marc_filename_hint='cu-electronic-2026-04.marc')

Pass nothing (the default) for pure-MARC format detection.

Verifying against the reference

The reference implementation is the behavioural contract. The tests port its JUnit suite to pytest and additionally diff goldrush's output for every record in tests/marc.dat against a golden file (tests/marc.dat.keys) generated by the reference coa_matchkey_v07312026.jar. To regenerate the golden file (requires Java and marc4j 2.9.6 on the classpath):

java -Dorg.coalliance.indexing.fileName= \
     -cp coa_matchkey_v07312026.jar:marc4j-2.9.6.jar \
     org.coalliance.matchkey.cli.MatchKeyCli tests/marc.dat > tests/marc.dat.keys

Credits and licensing

goldrush is licensed under the Apache License, Version 2.0.

The Gold Rush matchKey algorithm is the work of the Colorado Alliance of Research Libraries, and goldrush's field-extraction and normalization logic (src/goldrush/fields/, src/goldrush/util/, generator.py, and version.py) is a port of their Apache-2.0 reference implementation, coalliance-matchkey (Copyright 2026 Colorado Alliance of Research Libraries). The ISBN-validation logic additionally derives from the solrmarc-marc4j project. These attributions are recorded in NOTICE.