amazonfetch.pl - query Amazon web service for products and write them into Tellico XML
amazonfetch.pl [--version | [-?|-h|--help] | [-g|--debug] | [[-i|--noimages] | [[-d|--directory value] | [[-l|--locale value] | [[-w|--window value] [query query ... ]
This program will allow you to interactively query the Amazon product lines in various countries and write the selected titles into a Tellico file. Tellico is a KDE collection management application by Robby Stephenson; see http://www.periapsis.org/tellico/. The appication was recently known as Bookcase.
Since the Amazon SOAP service is designed for automated queries and returns everything it knows about a productin in one go there is no reason to limit the number of entries it can save after a query. This makes its design different from its sister program, imdbfetch.pl which screen scrapes web pages of the International Movie Data Base (IMDB).
This program needs several nonstandard perl classes to run. On running it the first time, you'll get a list of missing ones. Install them from CPAN repository or using the package management program of your linux distribution (e.g. urpmi). The main dependency is the Net::Amazon manpage.
amazonfetch.pl will report an optional dependency for a module Cache::File. This will significantly speed up display of entries already seen, but is not necessary for the function of the program.
You can run this program in fully interactive mode by invoking it with the program name only. In addition, you can pass it movie titles or their substrings as command line arguments which are processed first.
The program tries to make an intelligent guess on the Amazon server you want to search. See option -l | --locale value for details how to change it.
Before query strings are processed, you have to select the product line to query. Currently there are only two: books or dvd.
For each query string, a list of matches is returned. You can select one or more of them for storing. An empty query string stops querying and the stored movie details are written into a tellico XML file with a name ``amazon2tellico_$$.bc'' where $$ is program process number.
If you do not have Cache::File, you'll have to run the program with option -n | --nocache.
It is now possible to pass a valid ISBN, with or without hyphens, as a single keyword. The algorithm for deciding if a keyword is an ISBN is very simple (length and characters), but can easily be made more strict in the future if there is a need.
Note that you have to be in 'books' mode if you want to fetch books using the ISBN. If you are running the program in 'dvd' mode, book items retrived with ISBN will be skipped.
The output data files are valid tellico files which can be opened with standard File>Open or CTRL+O command. However, you can also use the File>Import>Import Tellico Data to read items into an existing collection file. Note that you can not mix collection types.
0.0.0, 20 Mar 2004, start of the project
1.0.0, 17 May 2004, first public version
1.0.1, 18 May 2004, exited if query did not return anything - my mistake
1.0.2, 18 May 2004, extract subtitle from title (UK books)
1.1.0, 24 May 2004, accept an ISBN as a query string
better subtitle extraction code
1.1.1, 24 May 2004, uncommented comment killed the script
1.2.0 09 Nov 2004, more robust LOCALE detection,
changes in Net::Amazon 0.31, rename Bookcase->Tellico
1.2.1 12 Nov 2004, options --noimages and --dir
contributed by Dylan Brewis
1.2.2 15 Nov 2004, a missing closing pod statement ate the init subroutine
1.2.3 15 Nov 2004, output filename renamed
1.2.4 15 Jan 2005, prelimiary support for two new locales: ca and fr
1.2.5 13 Jun 2005, option to pick locale from LANG or LANGUAGE env variables,
fix setting locale at command line
1.2.6 22 Aug 2005, use my own developer ID for Amazon Web Services, old one did not work
- add remaining product categories: vhs music classical (help appreciated)
- more testing with various products and amazon web servers.
- cover image retrival seems to work only occationally for the new locales: ca and fr
Please report bugs to the author.
You may distribute this program under the same terms as perl itself.
Heikki Lehvaslaiho, heikki a gmail com
Dylan Brevis dylan a dylan me uk
You can get the latest version of this program at http://lehvaslaiho.homelinux.org/progs/download/amazonfetch.pl
The rest of the documentation details each of the subroutines this program is composed of.
Example : init();
Description: Initialize non-standard perl modules and fail
gracefully if any of them is missing.
Checks that output directory is exists and is writable.
Returns : true on success
Exceptions : dies on fail
Caller : query()
see the LWP::UserAgent manpage
Arg [1] : arrayref to a list of found movie titles
Arg [2] : prompt string
Arg [3] : integer, default value, 0 is no default
Arg [4] : boolean, is empty selection allowed?
Arg [5] : integer, window size, defaults to 7
Example : picklist($items,$prompt,$default,1,10);
Description: Show a few of the items from a list at the time and
allow selecting one or many items. Note: If the subroutine is
called in scalar mode, only first item is read
Returns : array of picked list items
Exceptions : none
Caller : pick_a_movie()
Based on method in CPAN::FirstTime, See the CPAN::FirstTime manpage. Modified both internals and API.
Arg [1] : string, keuwords for one item
Example : fetch($string);
Description: Do the web query and ask user which of
the matches are worth keeping
Returns : nil
Exceptions : none
Caller : main()
Arg [1] : string, URL into thumbnail image Example : cover_image($url); Description: Retrieves a tiny jpg image of the cover Returns : string, base64 encoded jpg cover image or 0 Exceptions : none Caller : into_xml()
Arg [1] : arrayref to a list of movie detail hashrefs Example : into_xml($selected_movies); Description: convert data structure into bookcase version 5 XML Returns : XML string Exceptions : none Caller : store_into_file
Example : store_into_file
Description: write the kept details into bookcase XML file
in the working directory
Returns : true or false
Exceptions : none
Caller : main(), END block
Arg(s) : strings, keywords
Example :
Description: loop over command line arguments,
prompt for a query strings,
and store the entries into a bookcase XML file
Returns : nil
Exceptions : none
Caller :