Search For 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 through the section's content items:

If we want to search a tag, it is possible through the web service. The URL format required to search for a tag can be obtained from the URL in the above atom entry with relation type search. Submitting a GET request on the URL is like:

curl -u user:password 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 the tag for a specific tag structure:

<?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>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag:folksonomy.escenic.com,2002/tag:folksonomy.escenic.com,2002:ap" 
      rel="self" 
      title="Arbeiderpartiet"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag:folksonomy.escenic.com,2002/tag:folksonomy.escenic.com,2002:db:1346" 
      rel="http://www.escenic.com/types/relation/parent"
      title="politics"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag:folksonomy.escenic.com,2002" 
      rel="http://www.escenic.com/types/relation/top"
      title="Tags"/>
    <link 
      href="http://host-ip-address/webservice/escenic/classification/tag:folksonomy.escenic.com,2002/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.