pyzotero

Common errors

• KeyError: 'title' (or similar for other fields like 'name')

  cause Attempting to access item or collection data directly (e.g., `item['title']`) instead of through the nested `data` dictionary.
  fix Access fields via `item['data']['title']` or `collection['data']['name']`. The Zotero API response structure always wraps core data in a 'data' field.

• pyzotero.lib.ZoteroException: Could not authenticate with Zotero API. (401: Unauthorized)

  cause Incorrect `library_id`, `api_key`, or `library_type` ('user' vs 'group'). Also, insufficient API key permissions are a common cause.
  fix Double-check your `library_id`, `api_key`, and ensure the `library_type` matches your Zotero setup. Verify that the API key has the necessary permissions (e.g., read access for fetching data) in your Zotero account.

• (No explicit error, but unexpected behavior) "I'm only getting 25 items, but my Zotero library has hundreds."

  cause Using paginated methods like `zot.items()` which by default return a limited number of results (e.g., 25 or 50) per call, without explicitly handling further pages.
  fix For comprehensive lists, use `zot.all_items()` or `zot.all_collections()`. These methods handle pagination internally to retrieve all available entries. Alternatively, use the `limit` and `start` parameters on `zot.items()` for manual pagination.

Warnings

• gotcha Zotero API responses for items and collections are nested under a 'data' key. Direct access like `item['title']` will raise a KeyError.
  Fix: Always access item or collection properties via `item['data']['title']` or `collection['data']['name']`.
• gotcha Methods like `zot.items()` and `zot.collections()` return paginated results, often limited to 25 or 50 items by default. They do not retrieve all results in a single call.
  Fix: To retrieve all items or collections, use the `all_items()` or `all_collections()` methods (e.g., `zot.all_items()`). Alternatively, implement manual pagination using `limit` and `start` parameters.
• gotcha Zotero API keys are tied to specific permissions (e.g., read, write, modify). An API key lacking necessary permissions will result in authentication errors or disallowed operation errors.
  Fix: Before making API calls, verify that your Zotero API key has the required permissions configured in your Zotero account settings (https://www.zotero.org/settings/keys).

Install

• pip install pyzotero Install latest version

Imports

• Zotero
  wrong:

  import pyzotero.Zotero

  correct:

  from pyzotero import Zotero

  The Zotero class is directly importable from the top-level package.

Quickstart

This quickstart initializes the Zotero client and fetches the first few collections and items from your library. It demonstrates accessing nested data fields and uses environment variables for secure credential management.

import os
from pyzotero import Zotero

# Your Zotero user ID or group ID
library_id = os.environ.get('ZOTERO_LIBRARY_ID', 'YOUR_LIBRARY_ID') # Replace 'YOUR_LIBRARY_ID' if not using env var
# Your Zotero API key
api_key = os.environ.get('ZOTERO_API_KEY', 'YOUR_API_KEY') # Replace 'YOUR_API_KEY' if not using env var

# 'user' for personal library, 'group' for group library
library_type = 'user'

if not library_id or not api_key:
    print("Please set ZOTERO_LIBRARY_ID and ZOTERO_API_KEY environment variables or replace placeholders.")
else:
    try:
        # Initialize Zotero object
        zot = Zotero(library_id, library_type, api_key)

        # Fetch top-level collections
        collections = zot.collections()
        print(f"Found {len(collections)} collections.")
        if collections:
            print(f"First collection name: {collections[0]['data']['name']}")

        # Fetch 5 items from the library
        items = zot.items(limit=5)
        print(f"Found {len(items)} items.")
        if items:
            print(f"First item title: {items[0]['data']['title']}")

    except Exception as e:
        print(f"An error occurred: {e}")