Docs
Search K

Appearance

Writing Bots ​

For legacy documentation, please check the Open Library Archives. Most Bot code now lives at https://github.com/internetarchive/openlibrary-bots

Introduction ​

If you encounter recurring metadata errors on Open Library editions, works, or authors; notice duplicate authors that should be merged; find fake books that should be deleted; or want to import missing books from other sources, these tasks can be handled by bot accounts.

Open Library bot accounts make HTTP POSTs to work, author, edition, and subject pages to correct metadata or create and import new records (books, authors, book covers) in bulk.

Applying for a Bot Account ​

To apply for a privileged bot account:

  1. Register a new Open Library account that meets these guidelines:
    • The bot account must be separate from your personal Open Library account.
    • The username must end with "Bot" (for example, WorkBot, ImportBot).
    • These conventions enable filtering Recent Changes by bots to identify changes made by bot accounts. Bots perform repetitive operations at high frequency and would overwhelm the list if shown alongside human edits.
  2. Open a GitHub issue and ask a site admin (for example, @mekarpeles or @hornc) to grant bot privileges to your account and add it to the "API" usergroup.

Getting Started: Rules ​

Question: I have a bot account. Can I start fixing thousands of problems immediately?

Answer: Do not run a bot script to change metadata in bulk (more than 100 records) until it has been reviewed by Charles (@hornc on GitHub). The correct process is to create a new directory for your bot in the https://github.com/internetarchive/openlibrary-bots repository, open a PR, and add Charles (@hornc) or Mek (@mekarpeles) as a reviewer.

Question I have a metadata question about how my bot should work, a question about using the openlibrary-client, or I need a code review for my bot. Who do I ask?

Answer: @hornc (Charles on Slack) leads metadata and can answer questions about the openlibrary-client and writing/registering bots to fix metadata or add new books to the catalog.

Question: I have written a bot. Am I ready to run it?

Answer: If your bot script is ready, fork the https://github.com/internetarchive/openlibrary-bots repository, create a new branch, add a directory named according to the action your bot will perform, and submit a PR for review. Do not run bulk modifications until @hornc or @mekarpeles has reviewed and approved your script, or your bot privileges may be revoked.

Question: My bot reads metadata from a source file and modifies records on Open Library. Should these source data files be saved?

Answer: Yes. If your bot adds new or updated metadata from files, commit those files with your script to https://github.com/internetarchive/openlibrary-bots.

openlibrary-client Library ​

Instead of making POSTs directly to API endpoints using a bot account, use the official Python client library openlibrary-client, which streamlines metadata updates and bot development. The older openlibrary/api.py library has been deprecated in favor of the easier and safer openlibrary-client.

Bot Account Etiquette ​

Avoid using bot accounts directly for one-off changes from the command line. Instead, code changes into bot scripts and check them into the openlibrary-bots repository. This allows the team to review what changes were made, debug issues, and update or re-apply logic as needed.

Example Bots ​

Here's an example by @hornc of a bot that uses openlibrary-client for merging works and editions and updating records in bulk.

The following legacy examples used api.py (now deprecated) instead of openlibrary-client. They illustrate what Open Library bots do, how they are written, and how they are used. Refer to the openlibrary-client documentation for modern examples:

Bot Opportunities ​

Migrated to https://github.com/internetarchive/openlibrary/issues/2863

Also see Ideas for new bots.