LibriVoxAPI

From Librivox wiki
Jump to navigationJump to search

The following API exist for software integration with the LibriVox Catalog


Downloading the whole catalog: XML, OPML, CSV, Text

The most friendly way to get at the whole catalog is to page your way through it. The preferred API for doing this is:

http://librivox.org/newcatalog/latestworks.xml?offset=0&limit=50

offset and limit are optional parameters, defaulting to 0 and 50 respectively, and work like the SQL search parameters of the same names. The list of latest works is ordered from the most recent.

(If you want to access a particular project, you can also use the latestworks.xml call with the parameter id=xxxx)

Most integrators have walked their way once through the back catalog with this API, and then periodically call it with offset=0 to get new works. If you do this, it's worth knowing that the id parameter in the book tag uniquely identifies a work.

If you prefer OPML, there is a much less data-rich option that will give you the whole catalog in one hit.

http://librivox.org/newcatalog/latestworks.opml?v=2

For a .csv file, try this:

http://librivox.org/newcatalog/csv.php

and a low information content text version:

http://librivox.org/newcatalog/text_catalog.php

Searching the catalog

By far the most integration-friendly way to search the catalog is:

http://librivox.org/newcatalog/search_xml.php?extended=1&simple=Austen

The simple parameter can take multiple terms (logical AND), and is used to search Author, Title, language, genre, category and maybe some other stuff. Not case sensitive.

If you know the id of a work you can also use id=xxxx in place of simple.

You can also use genre=xxxx for a genre based search, or title=xxxx or author=xxxx for title or author searches. Note that author searches currently search first author only.

Title and author searches also allow you to specify that you want to get only things that match the beginning of the field (for instance, if you are doing a 'search as they type' sort of application. Do this by inserting a '^' at the start of the search term:

http://librivox.org/newcatalog/search_xml.php?extended=1&title=^all

Accessing individual audio files

All of the above ways of finding works provide you with an RssURL. Use it!

If you want to access the ogg files, you have two options. If the RssURL is of the form http://librivox.org/rss/xxxx then just replace rss with rssogg. Alternatively, simply replace the _64kb.mp3 at the end of the filename with .ogg.

To get the 128kb mp3 files, simply replace the _64kb.mp3 at the end of the filename with .mp3.

MARC21

This is really experimental at the moment, but you can try

http://librivox.org/newcatalog/MARC21/marc.pl?pid=xxxx

http://librivox.org/newcatalog/MARC21/marc.pl?pid=xxxx&human=1

where xxxx is a project ID (probably extracted from the xml calls above) to get a machine readable or human readable MARC21 record.

A complete MARC21 catalog is generated daily:

http://librivox.org/newcatalog/MARC21/librivox.mrc.gz

Finding out more

These APIs have been developed in response to particular requests. If you'd like more information, or have a particular request we might be able to help with, email info@librivox.org.