WWW::Zotero(3pm)

📦 version 0.04, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

WWW::Zotero 💖

okay so bestie, this is the User Contributed Perl Documentation page for WWW::Zotero, and it's literally your all-access pass to the Zotero API from Perl. no cap, it's giving "i have 4,000 citations and i'm not afraid to use them" energy. let's go 🦋

✨ NAME ✨

WWW::Zotero — a Perl interface to the Zotero API 💅

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready, exactly as written:

use WWW::Zotero;

my $client = WWW::Zotero->new;
my $client = WWW::Zotero->new(key => 'API-KEY');

my $data = $client->itemTypes();

for my $item (@$data) {
    print "%s\n" , $item->itemType;
}

my $data   = $client->itemFields();
my $data   = $client->itemTypeFields('book');
my $data   = $client->itemTypeCreatorTypes('book');
my $data   = $client->creatorFields();
my $data   = $client->itemTemplate('book');
my $key    = $client->keyPermissions();
my $groups = $client->userGroups($userID);

my $data   = $client->listItems(user => '475425', limit => 5);
my $data   = $client->listItems(user => '475425', format => 'atom');
my $generator = $client->listItems(user => '475425', generator => 1);

while (my $item = $generator->()) {
    print "%s\n" , $item->{title};
}

my $data = $client->listItemsTop(user => '475425', limit => 5);
my $data = $client->listItemsTrash(user => '475425');
my $data = $client->getItem(user => '475425', itemKey => 'TTJFTW87');
my $data = $client->getItemTags(user => '475425', itemKey => 'X42A7DEE');
my $data = $client->listTags(user => '475425');
my $data = $client->listTags(user => '475425', tag => 'Biography');
my $data = $client->listCollections(user => '475425');
my $data = $client->listCollectionsTop(user => '475425');
my $data = $client->getCollection(user => '475425', collectionKey => 'A5G9W6AX');
my $data = $client->listSubCollections(user => '475425', collectionKey => 'QM6T3KHX');
my $data = $client->listCollectionItems(user => '475425', collectionKey => 'QM6T3KHX');
my $data = $client->listCollectionItemsTop(user => '475425', collectionKey => 'QM6T3KHX');
my $data = $client->listCollectionItemsTags(user => '475425', collectionKey => 'QM6T3KHX');
my $data = $client->listSearches(user => '475425');

periodt. that's the whole tour 💖

🎀 CONFIGURATION 🎀

the little knobs you can turn when you build your client:

`baseurl`

The base URL for all API requests. Default is 'https://api.zotero.org'. 🏠

`version`

The API version. Default is '3'. ✨

`key`

The API key, which you can request via https://api.zotero.org. 🔑 (guard this with your life, bestie, it's your main character credential)

`modified_since`

Drop in a UNIX time and it gets used in an If-Modified-Since header, so your app can cache results instead of re-fetching everything like a menace. 🕰️

🔥 METHODS 🔥

okay this is the part where it gets good. buckle up 🫶

`username2userID`

Find the userID based on a username. 🔍

`itemTypes()`

Get all item types. Returns a Perl array. 🗂️

`itemTypes()`

Get all item fields. Returns a Perl array. 👀

ngl bestie, yes — itemTypes() is listed twice in this page, once for item types and once for item fields. i'm not the one who did that, i'm just the messenger, and the facts stay the facts 💀

`itemTypes($type)`

Get all valid fields for an item type. Returns a Perl array. 📋

`itemTypeCreatorTypes($type)`

Get valid creator types for an item type. Returns a Perl array. ✍️

`creatorFields()`

Get localized creator fields. Returns a Perl array. 🌍

`itemTemplate($type)`

Get a template for a new item. Returns a Perl hash. 📝

`keyPermissions($key)`

Return the userID and premissions for the given API key. 🔐

(spelled exactly like that in the source, and we respect the source 💅)

`userGroups($userID)`

Return an array of the set of groups the current API key as access to. 👯

`listItems(user => $userID, %options)`

`listItems(group => $groupID, %options)`

List all items for a user or ar group. Optionally provide a list of options:

sort — dateAdded, dateModified, title, creator, type, date, publisher, publicationTitle, journalAbbreviation, language, accessDate, libraryCatalog, callNumber, rights, addedBy, numItems (default dateModified)
direction — asc, desc
limit — integer 1-100* (default 25)
start — integer
format — perl, atom, bib, json, keys, versions , bibtex , bookmarks, coins, csljson, mods, refer, rdf_bibliontology , rdf_dc , rdf_zotero, ris , tei , wikipedia (default perl)
when format => 'json'
- include — bib, data
when format => 'atom'
- content — bib, html, json
when format => 'bib' or content => 'bib'
- style — chicago-note-bibliography, apa, ... (see: https://www.zotero.org/styles/)
itemKey — A comma-separated list of item keys. Valid only for item requests. Up to 50 items can be specified in a single request.
itemType — Item type search
q — quick search
qmode — titleCreatorYear, everything
since — integer
tag — Tag search

See: https://www.zotero.org/support/dev/web_api/v3/basics#user_and_group_library_urls for the search syntax. 🔗

Returns a Perl HASH containing the total number of hits plus the results:

{
    total => '132',
    results => <data>
}

`listItems(user => $userID | group => $groupID, generator => 1 , %options)`

Same as listItems but this return a generator for every record found. Use this method to sequentially read the complete resultset. E.g.

my $generator = $self->listItems(user => '231231', generator);

while (my $record = $generator->()) {
    printf "%s\n" , $record->{title};
}

The format is implicit 'perl' in this case. 🌀