Developers Wiki - CosmosQuery

Cosmos Query

Info

Cosmos lets you see what blogs are linking to a given URL. On the Technorati site, you can enter a URL in the searchbox and it will return a list of blogs linking to it. The API version allows more features and gives you a way to use the cosmos on your own site.

Format

The call is made using a REST-ful interface. Send either a HTTP GET or a HTTP POST to http://api.technorati.com/cosmos?key=<apikey>&url=<url> with mandatory parameters "key" and "url" and additional optional parameters described below.

Parameters

key (mandatory) - Provide your Technorati API key in here, which you can obtain at http://www.technorati.com/developers/apikey.html.
url (mandatory) - Set this to the target URL you are searching for. The 'http://' prefix is optional.
type - Set this to link and you'll get the freshest links to your target URL. Set it to weblog and you'll get a reverse blogroll - the last set of blogs that linked to the target URL.
limit - Set this to a number larger than 0 and smaller or equal to 100 and it will return <limit> number of links for a query. By default this value is 20.
start - Set this to a number larger than 0 and you'll get the <start>+<limit> freshest items (links or blogs), e.g. set it to <limit>+1, and you'll get the second page of rankings.
current - By default, cosmos returns the links that are currently on the source's index page. If you set current to no, you will have all links to the given URL.
format - This allows you to request an output format, which by default is set to xml. At the moment only the XML and RSS formats are supported. Atom and XOXO should be supported soon.
claim - Set this to 1 to have each link result embellished with any user information associated with a link result blog.
highlight - Set this to 1 to have each link result excerpt highlight what text was linked.

Response

The cosmos query either returns a list of links and associated info or an error message. Error responses are always in default XML format and look like this:

<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /cosmos" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN" "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
<document>
<result>
  <error>ERROR MESSAGE</error>
</result>
</document>
</tapi>

On success, and for the xml format and link type, the response is as follows:

<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /cosmos" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN" "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
<document>
<result>
  <url>QUERY URL</url>
  <weblog>
    <name>BLOG NAME</name>
    <url>BLOG URL</url>
    <rssurl>BLOG RSS URL</rssurl>
    <atomurl>BLOG ATOM URL</atomurl>
    <inboundblogs>NUMBER OF INBOUND BLOGS</inboundblogs>
    <inboundlinks>NUMBER OF INBOUND LINKS</inboundlinks>
    <lastupdate>DATE BLOG WAS LAST UPDATED</lastupdate>
    <rank>COSMOS RANKING</rank>
  </weblog>
  <inboundblogs>NUMBER OF INBOUND BLOGS</inboundblogs>
  <inboundlinks>NUMBER OF INBOUND LINKS</inboundlinks>
  <rankingstart>START PARAMETER VALUE</rankingstart>
</result>
<item>
  <weblog>
    <name>BLOG NAME</name>
    <url>BLOG URL</url>
    <rssurl>BLOG RSS URL</rssurl>
    <atomurl>BLOG ATOM URL</atomurl>
    <inboundblogs>INBOUND BLOGS</inboundblogs>
    <inboundlinks>INBOUND LINKS</inboundlinks>
    <lastupdate>LAST UPDATED TIME STAMP</lastupdate>
  </weblog>
  <nearestpermalink>LINK TO BLOG'S INDIVIDUAL ENTRY CONTAINING LINK TO THE QUERY URL</nearestpermalink>
  <excerpt>EXCERPT CONTAINING QUERY URL</excerpt>
  <linkcreated>DATE LINK WAS CREATED</linkcreated>
  <linkurl>URL THAT WAS LINKED TO</linkurl>
</item>
...
</document>
</tapi>

If the cosmos'd URL is not a blog, the <weblog /> element will be absent from the <result />, i.e. it will look like this:

<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /cosmos" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN" "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
<document>
<result>
  <url>QUERY URL</url>
  <inboundblogs>NUMBER OF INBOUND BLOGS</inboundblogs>
  <inboundlinks>NUMBER OF INBOUND LINKS</inboundlinks>
  <rankingstart>START PARAMETER VALUE</rankingstart>
</result>
<item>
  <weblog>
    <name>BLOG NAME</name>
    <url>BLOG URL</url>
    <rssurl>BLOG RSS URL</rssurl>
    <atomurl>BLOG ATOM URL</atomurl>
    <inboundblogs>INBOUND BLOGS</inboundblogs>
    <inboundlinks>INBOUND LINKS</inboundlinks>
    <lastupdate>LAST UPDATED TIME STAMP</lastupdate>
  </weblog>
  <nearestpermalink>LINK TO BLOG'S INDIVIDUAL ENTRY CONTAINING LINK TO THE QUERY URL</nearestpermalink>
  <excerpt>EXCERPT CONTAINING QUERY URL</excerpt>
  <linkcreated>DATE LINK WAS CREATED</linkcreated>
  <linkurl>URL THAT WAS LINKED TO</linkurl>
</item>
...
</document>
</tapi>

The date is set to standard format as in: 2004-02-04 06:28:26 GMT.

If the claim parameter is included, the results with an author associated with it (i.e. the blog is claimed) will look like this

<?xml version="1.0" encoding="utf-8"?>
<!-- generator="Technorati API version 1.0 /cosmos" -->
<!DOCTYPE tapi PUBLIC "-//Technorati, Inc.//DTD TAPI 0.02//EN" "http://api.technorati.com/dtd/tapi-002.xml">
<tapi version="1.0">
<document>
<result>
  <url>QUERY URL</url>
  <inboundblogs>NUMBER OF INBOUND BLOGS</inboundblogs>
  <inboundlinks>NUMBER OF INBOUND LINKS</inboundlinks>
  <rankingstart>START PARAMETER VALUE</rankingstart>
</result>
<item>
  <weblog>
    <name>BLOG NAME</name>
    <url>BLOG URL</url>
    <rssurl>BLOG RSS URL</rssurl>
    <atomurl>BLOG ATOM URL</atomurl>
    <inboundblogs>INBOUND BLOGS</inboundblogs>
    <inboundlinks>INBOUND LINKS</inboundlinks>
    <lastupdate>LAST UPDATED TIME STAMP</lastupdate>
    <author>
      <username>USERNAME</username>
      <firstname>FIRST NAME</firstname>
      <lastname>LAST NAME</lastname>
      <thumbnailpicture>URL TO THUMBNAIL PICTURE (IF PRESENT)</thumbnailpicture>
    </author>
  </weblog>
  <nearestpermalink>LINK TO BLOG'S INDIVIDUAL ENTRY CONTAINING LINK TO THE QUERY URL</nearestpermalink>
  <excerpt>EXCERPT CONTAINING QUERY URL</excerpt>
  <linkcreated>DATE LINK WAS CREATED</linkcreated>
  <linkurl>URL THAT WAS LINKED TO</linkurl>
</item>
...
</document>
</tapi>

Feature Request

AlternateUrlCosmos

Nov	DEC	Feb
	25
2004	2005	2007