/ 
Net-PicApp-0.3
River stage zero No dependents
/ Net::PicApp

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>