zemanta.suggest_markup

Suggest method allows developers to query Zemanta for contextual metadata on a given text. In comparison to zemanta.suggest, this method returns only links (to semantical entities)

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.

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.

Function input parameters

Response structure

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
• techcrunch
• musibrainz
• twitter
• mybloglog
• facebook
• itis (Integrated Taxonomic Information System)
• ncbi (National Center for Biotechnology Information)
• stockexchange
• rdf (for semantic links to dbPedia, Freebase, MusicBrainz and Semantic TechCrunch)

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_markup',
        '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.',
        'format': 'xml'}
args_enc = urllib.urlencode(args)
print urllib.urlopen(gateway, args_enc).read()

Sample return (Truncated for clarity)

<rsp>
  <status>ok</status>
  <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>
<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 you 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 that you can compare confidence values between documents. 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.