NAME

Net::PicApp - A toolkit for interacting with the PicApp service.

SYNOPSIS

   my $picapp = Net::PicApp->new({
    apikey => '4d8c591b-e2fc-42d2-c7d1-xxxabc00d000'
   });
   my $response = $picapp->search('cats');
   if ($response->is_success) {
     foreach my $img (@{$response->images}) {
       print $img->imageTitle . "\n";
     }
   } else {
     die $picapp->error_message;
   }
   

DESCRIPTION

This module provides a convenient interface to the PicApp web service. It requires that you have been given an API Key by PicApp.

PREREQUISITES

PicApp API Key

XML::Simple

LWP

USAGE

METHODS

search($terms, %options)

This function receives a term for searching and retrieves the results in XML. This function allows the user to send search parameters in addition to the search term, corresponding to advanced search options in the www.picapp.com website.

Search Options:

no_cache - if set to true, then the cache will be forcibly bypassed for this one request

with_thumbnails - boolean

category - "Editorial" or "Creative" (default: all)

subcategory - A sub-category by which to filter. See Constants.

colors - "BW" or "Color" (default both)

orientation - "Horizontal" or "Vertical" or "Panoramic" (default: all)

types - "Photography" or "Illustration" (default: all)

match_phrase - "AllTheseWords" or "ExactPhrase" or "AnyTheseWords" or "FreeText"

time_period - "Today" or "Yesterday" or "Last3Days" or "LastWeek" or "LastMonth" or "Last3Months" or "Anytime"

sort - How to sort the results (by relevancy, by recency, or randomly). See Constants.

page - This parameter depicts the page number (1 and above) to be retrieved from the system.

total_records - This parameter indicates the maximal number of results requested from Picapp (1 and above).

Usage Notes:

If with_thumbnails has been specified and is true, then this function will retrieve the search results upon user definitions with extra rectangular cropped thumbnails on top of the regular thumbnail. These thumbnails will be available in the response object.

If subcategory OR contributor has been specified then this function will also filter the search results by image contributor (Getty, Corbis, Splash, etc..) and by image category (news, creative, sports, etc..)

get_image_details($id, $options)

This function receives the unique key and the image ID (the image ID received from the search XML results).

Options:

no_cache - if set to true, then the cache will be forcibly bypassed for this one request

does_user_exist($username, $password)

This function receives a login name a password and retrieves an xml with the user details.

publish( $id, $terms, $email, $options )

This function receives an image ID, the search terms used to find the image and an email address and then retrieves the script in XML.

Options:

size - 1 depicts 234, 2 depicts 350 and 3 depicts 420

image_frame -

CONSTANTS

The following constants have been defined to assist in specifying the appropriate values to a search request:

Contributors

CONTRIB_CORBIS

CONTRIB_ENTERTAINMENT_PRESS

CONTRIB_GETTY

CONTRIB_IMAGE_SOURCE

CONTRIB_JUPITER

CONTRIB_NEWSCOM

CONTRIB_PACIFIC_COAST

CONTRIB_SPLASH

Sub-Categories

CAT_EDITORIAL

CAT_CREATIVE

CAT_ENTERTAINMENT

CAT_NEWS

CAT_SPORTS

Sort Values

SORT_RELEVANT

SORT_RECENT

SORT_RANDOM

INITIALIZATION OPTIONS

Each of the following options are also accessors on the main Net::PicApp object.

apikey

The API Key given to you by PicApp for accessing the service.

url

The base URL of the PicApp service. Defaults to: 'http://api.picapp.com/API/ws.asmx'

cache

A Cache object to use for caching results.

CACHING

Responses returned by Amazon's web service can be cached locally. Net::Amazon's new method accepts a reference to a Cache object. Cache (or one of its companions like Cache::Memory, Cache::File, etc.) can be downloaded from CPAN, please check their documentation for details. In fact, any other type of cache implementation will do as well, see the requirements below.

Here's an example utilizing a file cache which causes Net::PicApp to cache responses for 30 minutes:

    use Cache::File;

    my $cache = Cache::File->new( 
        cache_root        => '/tmp/mycache',
        default_expires   => '30 min',
    );

    my $picapp = Net::PicApp->new(
        apikeykey  => 'YOUR_APIKEY',
        cache       => $cache,
    );

SEE ALSO

VERSION CONTROL

http://github.com/byrnereese/perl-Net-PicApp

AUTHORS and CREDITS

Author: Byrne Reese <byrne@majordojo.com>

cpanm Net::PicApp

perl -MCPAN -e shell
install Net::PicApp