zemanta.suggest

Suggest method allows developers to query Zemanta for contextual metadata about a given text. There are currently four main components of response: articles, keywords, images, in-text links and optional component categories.

Application submits text, either as HTML or plain text, and receives a number of suggestions back. It should be noted that HTML means text with markup such as links, bold and similar, it does not mean you can send whole page including navigation into the API. You should only send the "pure content". This document is primarily concerned with the formating of input and out parameters of a request, for precise explanation how each suggestion is made, please refer to Zemanta API Companion.

Function input parameters

Parameters in green should be passed directly from the response of zemanta.preferences call. Do not try to put your own values there.

About response formats

- xml
Generally XML is the format for interchange of information on internet. Zemanta offers a simple XML response format for its zemanta.suggested call.

- json
In scripting languages sometimes JSON is more natural format to parse, so you can use "json" as format, to get such response. Generally it is structured the same as "xml" format mentioned above.

- wnjson
In JavaScript there are additional issues in calling Zemanta API. You cannot send cross-domain POST requests in JavaScript (and you need that to send large chunks of text to Zemanta API). Recently a new method has been invented by JavaScript frameworks. You can open such call inside IFrame and then read the content of the window title to get to the plain JSON. Generally you should use frameworks such as jQuery that support this kind of calls natively. We call this response format "wnjson".

- rdfxml
Since Zemanta is a semantic application it is expected that proper semantic response is offered. When specifying "rdfxml" format you will get RDF/XML structure as response. We suggest using semantic libraries to read the triples encoded inside. All objects inside this response are properly typed and we have documented it on a separate page.  There you can also find more information about possible uses of Zemanta in semantic software/projects/ecosystems. Response is more precisely described in an "Zemanta RDF response" document.

Response structure (top level)

Articles substructure

Articles substructure is a list of article objects where each object has the following format:

Keywords substructure

Keywords substructure is a list of keyword objects where each object has the following format:

Images substructure

Images substructure is a list of image objects where each object has the following format:

Markup substructure

Markup substructure has two substructures:

Structure of each link object

Structure of each target object

Type can be one of the following strings:

• wikipedia
• amazon
• imdb
• youtube
• homepage
• geolocation
• blog
• crunchbase
• musibrainz
• twitter
• mybloglog
• facebook
• myspace
• itis (Integrated Taxonomic Information System)
• ncbi (National Center for Biotechnology Information)
• stockexchange
• lastfm
• snooth
• rdf (for semantic links to dbPedia, Freebase, MusicBrainz and Semantic TechCrunch)

Categories substructure

Categories substructure is a list of category objects where each object has the following format:

If you don't have special arragement with Zemanta you can only get "dmoz" as categorization.

Examples how API can be used in different langauges (PHP, Perl, C#, ...) are available in the wiki.

Sample call (python)

import urllib

gateway = 'http://api.zemanta.com/services/rest/0.0/'
args = {'method': 'zemanta.suggest',
        'api_key': 'key1234',
        'text': '''The Phoenix Mars Lander has successfully deployed its robotic arm and
tested other instruments including a laser designed to detect dust,
clouds, and fog. The arm will be used to dig up samples of the Martian
surface which will be analyzed as a possible habitat for life.''',
        'return_categories': 'dmoz',
        'format': 'xml'}
args_enc = urllib.urlencode(args)
print urllib.urlopen(gateway, args_enc).read()

Sample response (Truncated for clarity)

<rsp>
  <status>ok</status>
  <articles>
    <article>
      <url>http://abcnews.go.com/Technology/story?id=5255072&amp;page=1</url>
      <confidence>0.048289</confidence>
      <published_datetime>2008-06-26T19:12:59Z</published_datetime>
      <title>Seeds of Life Found in Martian Soil</title>
      <zemified>0</zemified>
    </article>
    <article>
      <url>http://www.computerworld.com/action/article.do?command=viewArticleBasic&amp;articleId=9108238&amp;source=rss_topic54</url>
      <confidence>0.0479</confidence>
      <published_datetime>2008-07-09T13:00:00Z</published_datetime>
      <title>NASA: Mars Lander short circuit pushes up ice test</title>
      <zemified>0</zemified>
  </article>
  </articles>
  <markup>
    <text>The &lt;a class="zem_slink" href="http://en.wikipedia.org/wiki/Phoenix_%28spacecraft%29"&gt;Phoenix Mars Lander&lt;/a&gt; has successfully deployed its &lt;a class="zem_slink" href="http://en.wikipedia.org/wiki/Robotic_arm"&gt;robotic arm&lt;/a&gt; and tested other instruments including a laser designed to detect dust, clouds, and fog. The arm will be used to dig up samples of the &lt;a class="zem_slink" href="http://en.wikipedia.org/wiki/Mars"&gt;Martian&lt;/a&gt; surface which will be analyzed as a possible habitat for life.</text>
    <links>
      <link>
        <confidence>0.084166</confidence>
        <anchor>Phoenix Mars Lander</anchor>
        <target>
          <url>http://www.youtube.com/watch?v=tR91HkTZ9VY</url>
          <type>youtube</type>
          <title>Phoenix (spacecraft)</title>
        </target>
        <target>
          <url>http://en.wikipedia.org/wiki/Phoenix_%28spacecraft%29</url>
          <type>wikipedia</type>
          <title>Phoenix (spacecraft)</title>
        </target>
      </link>
      <link>
        <confidence>0.006165</confidence>
        <anchor>robotic arm</anchor>
        <target>
          <url>http://en.wikipedia.org/wiki/Robotic_arm</url>
          <type>wikipedia</type>
          <title>Robotic arm</title>
        </target>
      </link>
    </links>
  </markup>
  <images>
    <image>
      <description>PASADENA, CA - MAY 25:  Phoenix principal investigator, University of Arizona, Peter Smith (L) and Phoenix project manager, JPL, Barry Goldstein address a final press conference before an illustrative video of the Phoenix Mars Lander approaching Mars...</description>
      <attribution>Image by &lt;a href="http://www.daylife.com/source/Getty_Images"&gt;Getty Images&lt;/a&gt; via &lt;a href="http://www.daylife.com"&gt;Daylife&lt;/a&gt;</attribution>
      <license>Low resolution use allowed when backlinking</license>
      <source_url>http://www.daylife.com/image/097c92HarS9oN</source_url>
      <confidence>0.5</confidence>
      <url_s>http://cache.daylife.com/imageserve/097c92HarS9oN/75x75.jpg</url_s>
      <url_s_w>75</url_s_w>
      <url_s_h>75</url_s_h>
      <url_m>http://cache.daylife.com/imageserve/097c92HarS9oN/150x100.jpg</url_m>
      <url_m_h>113</url_m_h>
      <url_m_w>150</url_m_w>
      <url_l>http://cache.daylife.com/imageserve/097c92HarS9oN/150x100.jpg</url_l>
      <url_l_h>100.0</url_l_h>
      <url_l_w>150</url_l_w>
    </image>
    <image>
       <description>Day 2 14.19.40 Phoenix Mars Lander 3-D Anaglyphs</description>
       <attribution>Image by &lt;a href="http://www.flickr.com/photos/48836503@N00/2530611038"&gt;gate3003&lt;/a&gt; via Flickr</attribution>
       <license>License CreativeCommons Attribution only</license>
       <source_url>http://www.flickr.com/photos/48836503@N00/2530611038</source_url>
       <confidence>0.5</confidence>
       <url_s>http://farm4.static.flickr.com/3043/2530611038_f490407155_s.jpg</url_s>
       <url_s_w>75</url_s_w>
       <url_s_h>75</url_s_h>
       <url_m>http://farm4.static.flickr.com/3043/2530611038_f490407155_m.jpg</url_m>
       <url_m_w>220</url_m_w>
       <url_m_h>240</url_m_h>
       <url_l>http://farm4.static.flickr.com/3043/2530611038_f490407155.jpg</url_l>
       <url_l_w>458</url_l_w>
       <url_l_h>500</url_l_h>
    </image>
    <image>
      <description>An artist's rendition of the Phoenix Mars probe during landing. The sophisticated landing system on Phoenix allows the spacecraft to touch down within 10 km (6.2 miles) of the targeted landing area. Thrusters are started when the lander is 570 m (1900 feet) above the surface. The navigation system is capable of detecting and avoiding hazards on the surface of Mars.</description>
      <attribution>Image via &lt;a href="http://commons.wikipedia.org/wiki/Image:Phoenix_landing.jpg"&gt;Wikipedia&lt;/a&gt;</attribution>
      <license>Public domain</license>
      <source_url>http://commons.wikipedia.org/wiki/Image:Phoenix_landing.jpg</source_url>
      <confidence>0.99</confidence>
      <url_s>http://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/Phoenix_landing.jpg/75px-Phoenix_landing.jpg</url_s>
      <url_s_w>75</url_s_w>
      <url_s_h>69</url_s_h>
      <url_m>http://upload.wikimedia.org/wikipedia/commons/thumb/6/6a/Phoenix_landing.jpg/202px-Phoenix_landing.jpg</url_m>
      <url_m_w>202</url_m_w>
      <url_m_h>186</url_m_h>
      <url_l>http://upload.wikimedia.org/wikipedia/commons/6/6a/Phoenix_landing.jpg</url_l>
      <url_l_w>5200</url_l_w>
      <url_l_h>4800</url_l_h>
    </image>
  </images>
  <keywords>
    <keyword>
      <confidence>0.506297</confidence>
      <name>Mars</name>
      <scheme>general</scheme>
    </keyword>
    <keyword>
      <confidence>0.296248</confidence>
      <name>Phoenix</name>
      <scheme>general</scheme>
    </keyword>
  </keywords>
  <categories>
    <category>
      <confidence>0.231914</confidence>
      <categorization>dmoz</categorization>
      <name>Top/Science/Anomalies_and_Alternative_Science/Astronomy,_Alternative/Planetary_Anomalies</name>
    </category><category>
      <confidence>0.195886</confidence>
      <categorization>dmoz</categorization>
      <name>Top/Science/Astronomy/Solar_System/Planets/Mars</name>
    </category>
  </categories>
  <signature>&lt;div class="zemanta-pixie"&gt;&lt;a class="zemanta-pixie-a" href="http://reblog.zemanta.com/zemified/40b3d04b-5248-4256-a22b-c07ba38b2d9f/" title="Zemified by Zemanta"&gt;&lt;img class="zemanta-pixie-img" src="http://img.zemanta.com/reblog_e.png?x-id=40b3d04b-5248-4256-a22b-c07ba38b2d9f" alt="Zemanta Pixie" /&gt;&lt;/a&gt;&lt;/div&gt;</signature>
  <rid>40b3d04b-5248-4256-a22b-c07ba38b2d9f</rid>
</rsp>

Fine print

The request size is limited. Only first 8kb of text is going to be processed.

There are also limits in place for number of requests per day (as specified in Terms of service) and per second. If you go over these limits, the system will return an error message "403 Developer over quota". Contact us if you need to make more calls to our system.

While confidence information is available for certain analysis, it is very seldom the case that comparing confidence values between documents is meaningful. Generally they represent relative measure of confidence for the specific type of recommendation for that specific document. Value should also not be interpreted as probability. We do our best to return meaningful confidences, but generally you should consult us about their use.