Developer Center

Cosmos Query

A URL search allows you to retrieve results for blogs linking to a given base URL. Technorati's cosmos query allows you to specify a wide array of parameters to customize your result set.

Format

The API call uses a REST-ful interface. Send either a HTTP GET or HTTP POST to http://api.technorati.com/cosmos with the parameters listed below.

Parameters

Mandatory

key: Your Technorati API key, which you can obtain on our API key page.
url: The base target URL for which you are searching.

Optional

type: A value of link returns the freshest links referencing your target URL.; A value of weblog returns the last set of unique weblogs referencing your target URL.
limit: Adjust the size of your result from the default value of 20 to between 1 and 100 results.
start: Adjust the range of your result set. Set this number to larger than zero and you will receive the portion of Technorati's total result set ranging from start to start+limit. The default start value is 1.
current: The default setting of yes Technorati returns links that are currently on a weblog's homepage. Set this parameter to no if you would like to receive all links to the given URL regardless of their current placement on the source blog.
format: The default setting of xml returns results using XML and Technorati's proprietary doctype. Set this parameter to rss to receive results in the RSS 2.0 markup format.
claim: The default setting of 0 returns no user information about each weblog included in the result set when available. Set this parameter to 1 to include Technorati member data in the result set when a weblog in your result set has been successfully claimed by a member of Technorati.
highlight: The default setting of 1 highlights the citation of the given URL within the weblog excerpt. Set this parameter to 0 to apply no special markup to the blog excerpt.

Response

Success

Below are sample generic responses from a cosmos API call.

Default

Below is a sample result from a cosmos search for a blog URL.


<?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 POST CONTAINING CITATION</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 given URL is not a blog the weblog element and subelements will be absent from its normal location as a child of <result />.


<?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 POST CONTAINING CITATION</nearestpermalink>
  <excerpt>EXCERPT CONTAINING QUERY URL</excerpt>
  <linkcreated>DATE LINK WAS CREATED</linkcreated>
  <linkurl>URL THAT WAS LINKED TO</linkurl>
</item>
...
</document>
</tapi>

Claim

If the claim parameter is set to 1 the API server will return an author element set as a child of <weblog />.


<?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>