/ 
Net-Zemanta-0.7
River stage zero No dependents
/ Net::Zemanta::Suggest

NAME

Net::Zemanta::Suggest - Perl interface to Zemanta Suggest service

SYNOPSIS

use Net::Zemanta::Suggest;

my $zemanta = Net::Zemanta::Suggest->new(
		APIKEY => 'your-API-key' 
	);

my $suggestions = $zemanta->suggest(
		"Cozy lummox gives smart squid who asks for job pen."
	);

# Suggested images
for $image (@{$suggestions->{images}}) {
	$image->{url_m};
	$image->{description};
}

# Related articles
for $article (@{$suggestions->{articles}}) {
	$article->{url};
	$article->{title};
}

# In-text links
for $link (@{$suggestions->{markup}->{links}}) {
	for $target (@{$link->{target}}) {
		$link->{anchor}, " -> ", $target->{url};
	}
}

# Keywords
for $keyword (@{$suggestions->{keywords}}) {
	$keyword->{name};
}

METHODS

new()
Net::Zemanta::Suggest->new(PARAM => ...);

Acceptable parameters:

APIKEY

The API key used for authentication with the service.

MARKUP_ONLY

If set to true, a faster variant of the API call is made that only returns the markup element. Default is to provide everything (images, related articles, markup and tags).

USER_AGENT

If supplied the value is prepended to this module's identification string to become something like:

your-killer-app/0.042 Perl-Net-Zemanta/0.1 libwww-perl/5.8

Otherwise just Net::Zemanta's user agent string will be sent.

new() returns undef on error.

suggest()
$suggestions = $zemanta->suggest( text, PARAM => ... )

Requests suggestions for the given text. Suggestions are returned as a tree of hash and list references that correspond to the returned JSON data structure. The most important parameters and result elements are described bellow. For the full reference see http://developer.zemanta.com.

Optional parameters:

MARKUP_LIMIT

Number of in-text links to return (default is 10).

IMAGES_LIMIT

Number of images to return (default is 24).

ARTICLES_LIMIT

Number of related articles to return (default is 10).

IMAGE_MAX_W, IMAGE_MAX_H

Maximum width and height of returned images respectively (default is 300 by 300).

suggest() returns undef on error.

articles

Related articles. Contains a list of article objects, each having the following elements:

url

URL of the article.

title

Title of the article.

published_datetime

Date when article was published in ISO 8601 format.

keywords

Suggested keywords. Contains a list of keyword objects, each having the following elements:

name

Keyword name (may contain spaces)

images

Related images. Contains a list of image objects, each having the following elements:

url_l, url_m, url_s

URLs of a large, medium and small version of the picture respectively.

url_l_w, url_l_h, url_m_w, url_m_h, url_s_w, url_s_h

Width and height of large, medium and small version of the picture respectively.

license

String containing license terms.

description

String containing description

attribution

Attribution that must be posted together with the image.

source_url

URL of a web page where more information about the image can be found.

markup

An object containing the following elements:

text

HTML formatted input text with added in-text hyperlinks.

Suggested in-text hyperlinks. A list of link objects, each having the following elements:

anchor

Word or phrase in the original text that should be used as the anchor for the link.

target

List of possible targets for this link. Each target has the following elements:

url

Destination URL.

type

Type of the resource URL is pointing to.

title

Title of the resource.

rid

Request ID.

signature

HTML signature that should be appended to the text.

error()

If the last call to suggest() returned an error, this function returns a string containing a short description of the error. Otherwise it returns undef.

SEE ALSO

AUTHOR

Tomaz Solc <tomaz@zemanta.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Zemanta ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.