About Zemanta

Zemanta API is state of the art in text analysis.

For any input text you get entities, related images, articles, hyperlinks, and tags to use to your liking.

Start building

It's easy. Just three steps:

  1. Create developer account
  2. Obtain API key
  3. Get sample code

Documentation of method 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 while 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

Function input parameters

Parameter Description Required Possible values
method Method on the server Yes "zemanta.suggest_markup"
api_key Your API key Yes
text Input clear text or HTML formatted Yes
format requested output format Yes "xml", "json", "rdfxml"
freebase
 return freebase GUIDs for links
(DEPRECATED)
 No
 0, 1
emphasis
 terms to "emphasise" (even when not present in text) No
 string
return_rdf_links return URIs of Linking Open Data entities No
 0, 1
markup_limit Number of markup items to return No number

Response structure

Parameter Description Type Possible Values
status indicates the status of request string ok, fail
rid unique request id that can be used with calls that require it string 36 chars UUID4
markup object
 dict
signature
 signature to use (HTML blob)
 string

Markup substructure

Markup substructure has two substructures:

Markup object Description Type
text HTML formatted text with links string
links a list of objects list

Structure of each link object

Link object Description Always
 Type
anchor the word(s) in original text that should be anchored yes
 string
confidence confidence on 0.0 to 1.0 scale yes
 float
target a list of objects yes
 list
freebase_guid
 Freebase GUID (given when input parameter freebase = 1 and data is available) DEPRECATED - use return_rdf_links 
no
 string

Structure of each target object

url resource URL of the linked term string
type type of resource string
title title of resource string

Type can be one of the following strings:

You can also check API use sample code in different langauges (PHP, Perl, C#, ...).

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.