Search For a Tag

The feed returned by the root tag URL (http://host-ip-address/webservice/escenic/classification) includes a search link:

The atom feed return by the web service is given below:

<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <link href="http://host-ip-address/webservice/open-search/tag-search-description.xml" rel="search"/>
  ...
</feed>

If the client application follows this link:

curl -u user:password -X GET http://host-ip-address/webservice/open-search/tag-search-description.xml

The web service returns an OpenSearch document describing the URL format required to search for tags:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
  <ShortName>Tag Search</ShortName>
  <Description>Search for a tags</Description>
  <Url xmlns:tag="http://xmlns.escenic.com/2011/classification-tags" 
       type="application/atom+xml" 
       template="http://host-ip-address/webservice/escenic/classification/tag/search?searchTerms={searchTerms}&amp;
                 tagStructures={tag:tag-schemes?}&amp;startPage={startPage?}&amp;pageSize={count?}"/>
  <LongName/>
  <Developer/>
  <Attribution/>
  <SyndicationRight/>
  <AdultContent>false</AdultContent>
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

From this information the client can construct a URL that submits a query. All of the search parameters except searchTerms are optional. If the tagStructures parameter is omitted then all tag structures are searched for the specified search terms. It is tag titles that are searched, not tag terms, and "starts with", case-insensitive matching is used.

For example:

curl -u user:password http://host-ip-address/webservice/escenic/classification/tag/search?searchTerms=arbeid

will find the tag "Arbeiderpartiet":

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:thr="http://purl.org/syndication/thread/1.0">
  <id>http://host-ip-address/webservice/escenic/classification/tag/search</id>
  <title type="html">Search for &lt;em&gt;&lt;strong&gt;arbeid&lt;/strong&gt;&lt;/em&gt;</title>
  <link href="http://host-ip-address/webservice/escenic/classification/tag/search" rel="self"/>
  <author>
    <name>Escenic Classification Web Service - Search Tags</name>
  </author>
  <updated>2011-03-15T13:41:48.515Z</updated>
  <entry>
    <id>tag:folksonomy.escenic.com,2002:ap</id>
    <title type="text">Arbeiderpartiet</title>
    <updated>2011-03-15T10:17:59.919Z</updated>
    <content type="html">politics / &lt;em&gt;&lt;strong&gt;Arbeid&lt;/strong&gt;&lt;/em&gt;erpartiet</content>
    <content type="application/vnd.vizrt.payload+xml">
      <vdf:payload 
           model="http://host-ip-address/webservice/escenic/classification/model/tag"
           xmlns:vdf="http://www.vizrt.com/types">
        <vdf:field name="description">
          <vdf:value>Norwegian Labour Party</vdf:value>
        </vdf:field>
        <vdf:field name="aliases">
          <vdf:list/>
        </vdf:field>      
      </vdf:payload>
    </content>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag/tag:folksonomy.escenic.com,2002:ap" 
      rel="self" 
      title="Arbeiderpartiet"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag/tag:folksonomy.escenic.com,2002:db:1346" 
      rel="http://www.vizrt.com/types/relation/parent"
      title="politics"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag:folksonomy.escenic.com,2002" 
      rel="http://www.vizrt.com/types/relation/top"
      title="Tags"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag/children/tag:folksonomy.escenic.com,2002:ap" 
      rel="down"
      title="Arbeiderpartiet" thr:count="0"/>
  </entry>
</feed>

It is possible to limit the search to a specific tag structure by specifying the tagStructures parameter.