Pyzotero

PyZotero is a community skill for managing bibliographic references using the Zotero API through the pyzotero Python library, covering library access, collection management, item creation, attachment handling, and citation export for academic reference management.

What Is This?

Overview

PyZotero provides tools for programmatically managing Zotero bibliographic libraries through the Zotero web API. It covers library access that reads items, collections, and tags from personal and group libraries, collection management that organizes references into hierarchical folders with batch operations, item creation that adds new bibliographic entries with metadata fields from programmatic sources, attachment handling that uploads and retrieves PDF files and other documents linked to references, and citation export that generates formatted bibliographies in multiple styles. The skill enables researchers to automate reference management workflows.

Who Should Use This

This skill serves academic researchers managing large reference libraries for systematic reviews, research teams sharing group libraries across collaborators, and developers building tools that integrate with Zotero bibliographic data.

Why Use It?

Problems It Solves

Managing hundreds of references manually in Zotero is time-consuming for systematic literature reviews. Importing references from programmatic searches requires manual entry when APIs are not connected. Sharing reference collections across team members needs synchronized group library management. Exporting citations in different formats for various journals requires repeated manual formatting.

Core Highlights

Library reader retrieves items, collections, and tags from Zotero libraries. Collection organizer creates and manages hierarchical reference folders. Item creator adds bibliographic entries with structured metadata fields. Citation exporter generates formatted references in multiple output styles.

How to Use It?

Basic Usage

from pyzotero import (
  zotero)

zot = zotero.Zotero(
  library_id='12345',
  library_type='user',
  api_key='your-key')

items = zot.top(
  limit=10)
for item in items:
  data = item['data']
  print(
    f'{data.get("title","")}')
  print(
    f'  Type: '
    f'{data["itemType"]}')
  print(
    f'  Date: '
    f'{data.get("date","")}')

results = zot.items(
  q='machine learning',
  limit=20)
print(
  f'Found: '
  f'{len(results)}')

cols = zot.collections()
for c in cols:
  print(
    f'{c["data"]["name"]}'
    f': {c["meta"]'
    f'["numItems"]}'
    f' items')

Real-World Examples

from pyzotero import (
  zotero)

class ReferenceImporter:
  def __init__(
    self,
    library_id: str,
    api_key: str
  ):
    self.zot = (
      zotero.Zotero(
        library_id,
        'user',
        api_key))

  def add_article(
    self,
    title: str,
    authors: list[str],
    journal: str,
    year: str,
    doi: str = ''
  ) -> dict:
    template = (
      self.zot
        .item_template(
          'journalArticle'))
    template['title'] = (
      title)
    template[
      'publicationTitle'
    ] = journal
    template['date'] = year
    template['DOI'] = doi
    template[
      'creators'] = [{
        'creatorType':
          'author',
        'name': a}
      for a in authors]
    resp = (
      self.zot
        .create_items(
          [template]))
    return resp

  def batch_import(
    self,
    records:
      list[dict]
  ) -> int:
    count = 0
    for r in records:
      self.add_article(
        **r)
      count += 1
    return count

Advanced Tips

Use batch creation to add multiple items in a single API call reducing the number of requests for large imports. Filter items by collection key to retrieve references from specific project folders without loading the entire library. Use the tag system to mark items with review status labels for tracking progress in systematic reviews.

When to Use It?

Use Cases

Import references from a PubMed search into a Zotero collection automatically with structured metadata. Export a formatted bibliography from a project collection for inclusion in a manuscript. Build a systematic review workflow that tracks screening status using Zotero tags.

Related Topics

PyZotero, Zotero, reference management, bibliographies, citation export, academic research, and literature management.

Important Notes

Requirements

pyzotero Python package for Zotero API communication. Zotero account with API key generated from the settings page. Library ID for the target personal or group library.

Usage Recommendations

Do: use item templates from the API when creating new entries to ensure all required fields are included. Batch item creation requests to minimize API calls when importing many references. Organize references into collections before export to simplify bibliography generation.

Don't: exceed Zotero API rate limits by sending too many requests without delays between batches. Modify shared group library items without coordinating with collaborators since changes sync immediately. Store sensitive annotations in shared libraries without checking group privacy settings.

Limitations

Zotero API rate limits restrict the number of requests per period for bulk operations. Full-text content search is not available through the API and requires the Zotero desktop application. Attachment upload has storage limits based on the user's Zotero storage plan.