/ 
Net-Zemanta-0.2
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.

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 elements are described bellow. For the full reference see http://developer.zemanta.com.

Optional parameters:

FREEBASE

Set to 1 to include FreeBase (http://www.freebase.com) GUIDs with in-text markup.

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.

freebase_guid

FreeBase GUID (if suggest() was called with FreeBase support enabled)

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

Tomaž Šolc <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.