{"id":10178,"library":"pyzotero","title":"pyzotero","description":"Python wrapper for the Zotero API, enabling programmatic access to Zotero libraries for managing research references, collections, and items. It's currently at version 1.11.0 and typically releases new versions every few months, often including bug fixes and minor enhancements.","status":"active","version":"1.11.0","language":"en","source_language":"en","source_url":"https://github.com/urschrei/pyzotero","tags":["zotero","research","api-wrapper","citations","references","academia"],"install":[{"cmd":"pip install pyzotero","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the Zotero API.","package":"requests","optional":false}],"imports":[{"note":"The Zotero class is directly importable from the top-level package.","wrong":"import pyzotero.Zotero","symbol":"Zotero","correct":"from pyzotero import Zotero"}],"quickstart":{"code":"import os\nfrom pyzotero import Zotero\n\n# Your Zotero user ID or group ID\nlibrary_id = os.environ.get('ZOTERO_LIBRARY_ID', 'YOUR_LIBRARY_ID') # Replace 'YOUR_LIBRARY_ID' if not using env var\n# Your Zotero API key\napi_key = os.environ.get('ZOTERO_API_KEY', 'YOUR_API_KEY') # Replace 'YOUR_API_KEY' if not using env var\n\n# 'user' for personal library, 'group' for group library\nlibrary_type = 'user'\n\nif not library_id or not api_key:\n    print(\"Please set ZOTERO_LIBRARY_ID and ZOTERO_API_KEY environment variables or replace placeholders.\")\nelse:\n    try:\n        # Initialize Zotero object\n        zot = Zotero(library_id, library_type, api_key)\n\n        # Fetch top-level collections\n        collections = zot.collections()\n        print(f\"Found {len(collections)} collections.\")\n        if collections:\n            print(f\"First collection name: {collections[0]['data']['name']}\")\n\n        # Fetch 5 items from the library\n        items = zot.items(limit=5)\n        print(f\"Found {len(items)} items.\")\n        if items:\n            print(f\"First item title: {items[0]['data']['title']}\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always access item or collection properties via `item['data']['title']` or `collection['data']['name']`.","message":"Zotero API responses for items and collections are nested under a 'data' key. Direct access like `item['title']` will raise a KeyError.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Access fields via `item['data']['title']` or `collection['data']['name']`. The Zotero API response structure always wraps core data in a 'data' field.","cause":"Attempting to access item or collection data directly (e.g., `item['title']`) instead of through the nested `data` dictionary.","error":"KeyError: 'title' (or similar for other fields like 'name')"},{"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.","cause":"Incorrect `library_id`, `api_key`, or `library_type` ('user' vs 'group'). Also, insufficient API key permissions are a common cause.","error":"pyzotero.lib.ZoteroException: Could not authenticate with Zotero API. (401: Unauthorized)"},{"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.","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.","error":"(No explicit error, but unexpected behavior) \"I'm only getting 25 items, but my Zotero library has hundreds.\""}]}