Difference between revisions of "LibriVoxAPI"

From Librivox wiki
Jump to: navigation, search
(MARC21)
(Removed old API info (but saved locally if needed) and added link to new API)
 
Line 1: Line 1:
The following API exist for software integration with the LibriVox Catalog
+
September 11, 2013: The new API is under development, and information on the new API is available at [http://librivox.org/api/info http://librivox.org/api/info].
 
 
 
 
== 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:
 
 
 
<code>http://librivox.org/newcatalog/latestworks.xml?offset=0&limit=50</code>
 
 
 
<code>offset</code> and <code>limit</code> 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 <code>latestworks.xml</code> call with the parameter <code>id=xxxx</code>)
 
 
 
Most integrators have walked their way once through the back catalog with this API, and then periodically call it with <code>offset=0</code> 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.
 
 
 
<code>http://librivox.org/newcatalog/latestworks.opml?v=2</code>
 
 
 
For a .csv file, try this:
 
 
 
<code>http://librivox.org/newcatalog/csv.php</code>
 
 
 
and a low information content text version:
 
 
 
<code>http://librivox.org/newcatalog/text_catalog.php</code>
 
 
 
== Searching the catalog ==
 
 
 
By far the most integration-friendly way to search the catalog is:
 
 
 
<code>http://librivox.org/newcatalog/search_xml.php?extended=1&simple=Austen</code>
 
 
 
The <code>simple</code> 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 <code>id=xxxx</code> in place of <code>simple</code>.
 
 
 
You can also use <code>genre=xxxx</code> for a genre based search, or <code>title=xxxx</code> or <code>author=xxxx</code> 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:
 
 
 
<code>http://librivox.org/newcatalog/search_xml.php?extended=1&title=^all</code>
 
 
 
== 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 <code>http://librivox.org/rss/xxxx</code> then just replace <code>rss</code> with <code>rssogg</code>. Alternatively, simply replace the <code>_64kb.mp3</code> at the end of the filename with <code>.ogg</code>.
 
 
 
To get the 128kb mp3 files, simply replace the <code>_64kb.mp3</code> at the end of the filename with <code>.mp3</code>.
 
 
 
== MARC21 ==
 
 
 
 
 
 
 
AT PRESENT THESE LINKS APPEAR NOT TO WORK - WE HOPE THAT THERE WILL BE IMPROVED RECORDS AVAILABLE - BUT THIS WILL PROBABLY NOT HAPPEN UNTIL SOMETIME NEXT YEAR.
 
ADDED 5TH oCTOBER 2012 BY ANNISE
 
 
 
 
 
This is really experimental at the moment, but you can try
 
 
 
<code>http://librivox.org/newcatalog/MARC21/marc.pl?pid=xxxx</code>
 
 
 
<code>http://librivox.org/newcatalog/MARC21/marc.pl?pid=xxxx&human=1</code>
 
 
 
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:
 
 
 
<code>http://librivox.org/newcatalog/MARC21/librivox.mrc.gz</code>
 
 
 
== 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.
 

Latest revision as of 13:51, 11 September 2013

September 11, 2013: The new API is under development, and information on the new API is available at http://librivox.org/api/info.