Colbie Martin API

The Colbie Martin API (Application Program Interface) allows people to interact programmatically with Colbie Martin.

The Colbie Martin API is available free of charge, and it returns data generated by Colbie Martin in a form that can be easily integrated into an application or a website.

This is the first version of the Colbie Martin API. It provides a handful of basic calls, but there's a lot more funtionality on the way.

At this moment the Colbie Martin API accepts REST requests and returns the results in XML. We will be offering other ways to access the API as well as returning the results in a future version of the API.

We group the current API calls in three categories or levels: Site, News and Users

Site level API calls

coRank.Site.GetInfo
It returns general information about the site.
Parameters:
None

Example Request:
http://ColbieMartin.corank.com/api/coRank.Site.GetInfo
Example Response:
```
<corank siteid="437">
	<title>Title for this site</title>
	<descr>Description for this site</descr>
	<locale>en</locale>
	<ownerid>2735</ownerid>
	<vup>Interesting</vup>
	<vdown>Not for me</vdown>
	<sword>source</sword>
	<swords>sources</swords>
</corank>
```
Response Details:
- vup and vdown are the words defined for the "vote up" and "vote down" actions.
- sword is the word defined to refer to a source (source/friend/contact, etc).
- swords is the same word but in plural.
coRank.Site.GetCategories
It returns the list of categories defined for the site.
Parameters:
None

Example Request:
http://ColbieMartin.corank.com/api/coRank.Site.GetCategories
Example Response:
```
<corank siteid="437">
	<cat id="1" idname="arts">Arts and Design</cat>
	<cat id="2" idname="business">Business</cat>
	<cat id="4" idname="currentnews">Current News</cat>
	...
</corank>
```
Response Details:
- id is the numeric ID for that category.
- idname is the name used in URLs for that category, for example http://ColbieMartin.corank.com/tech/all/cat/arts
- The value between the <cat>...</cat> tags is the descriptive name for that category.
The response will contain all the categories defined for the site.
coRank.Site.GetTotalStats
It returns:
- The total number of registered users at the site.
  This number is not the total number of people who have visited or used the site, only registered users count.
- The total number of submitted stories
- The total number of votes made on the submitted stories
Parameters:
None

Example Request:
http://ColbieMartin.corank.com/api/coRank.Site.GetTotalStats
Example Response:
```
<corank siteid="437">
	<users>2455</users>
	<votes>12447</votes>
	<stories>821</stories>
</corank>
```

News level API calls

coRank.News.GetItem
It returns almost everything you need to know about a particular story. This is probably the most used function of the entire coRank API.
Parameters:
It may take either 'id' or 'url' but not both.

id
The numeric ID for the story.

url
The URL path for the story.

Example Request:
With the numeric ID: http://ColbieMartin.corank.com/api/coRank.News.GetItem/id=771
With the URL path: http://ColbieMartin.corank.com/api/coRank.News.GetItem/url=art-tells-the-technological-future
In the second example, we're requesting info for the item that can be retrieved directly by visiting http://ColbieMartin.corank.com/tech/story/art-tells-the-technological-future
Example Response:
```
<corank siteid="437">
	<items>
		<item id="4478" pvotes="221" nvotes="17" comments="12" catid="16"
			  senderid="2234" sendernick="joesmith"
			  urlname="story-about-nothing"
			  sdate="1170668942">
			<title>Story about nothing</title>
			<link>http://www.example.com/</link>
			<description>This story is about nothing at all</description>
			<tags>
				<tag>party</tag>
				<tag>love</tag>
			</tags>
		</item>
	</items>
</corank>
```
Response Details:
- The item tag always contains the following values:
  - id: The numeric ID for this story.
  - pvotes: Total number of positive votes at this moment.
  - nvotes: Total number of negative votes at this moment.
  - comments: Total number of comments at this moment.
  - catid: The numeric ID for the story's category
  - senderid: The numeric ID of the person who submitted the story. If anonymous submissions are allowed, the value will be 0 (zero).
  - sendernick: For convenience, the nick of the person who submitted the story. If anonymous submissions are allowed, the value will be "Anonymous" (no quotes).
  - urlname: The URL path for this story. For example, if the URL to access this story is http://ColbieMartin.corank.com/tech/story/art-tells-the-technological-future, the value of "urlname" will be "art-tells-the-technological-future" (no quotes).
  - sdate: Date when the story was posted (PST/PDT). The value is the number of seconds since 00:00:00 January 1, 1970 (Epoch).
- The value between the <link>...</link> tags is the complete URL to the original story.
- The value for the title and description tags are, well, the title and description of the story. Note that the contents of the description may use several lines, such as in:
```
			<description>This story is about nothing
as you may have guessed by now</description>
```
- The content between the tag tags are the tags assigned to the story. If no tags have been assigned, there won't be a <tags>...</tags> section.
coRank.News.GetItemFromUrl
This call is almost identical to the previous one, except that the parameter you pass is the target URL for the story.
Therefore it is the best function to find out whether a particular page has already been submitted to the site.
Parameters:

url
The URL for the target site

Example Request:
http://ColbieMartin.corank.com/api/coRank.News.GetItemFromUrl/url=http://www.example.com/article/1223.html
Here, we're requesting info for the story that points to the page http://www.example.com/article/1223.html
IMPORTANT: If the URL contains the question mark symbol ?, you must url-encode it when you make the call. That is, change the ? for a %3F
If no entry with that URL is found, it will return the standard error "No story found"
Example Response:
```
<corank siteid="437">
	<items>
		<item id="4478" pvotes="221" nvotes="17" comments="12" catid="16"
			  senderid="2234" sendernick="joesmith"
			  urlname="story-about-nothing"
			  sdate="1170668942">
			<title>Story about nothing</title>
			<link>http://www.example.com/</link>
			<description>This story is about nothing at all</description>
			<tags>
				<tag>party</tag>
				<tag>love</tag>
			</tags>
		</item>
	</items>
</corank>
```
Response Details:
- The item tag always contains the following values:
  - id: The numeric ID for this story.
  - pvotes: Total number of positive votes at this moment.
  - nvotes: Total number of negative votes at this moment.
  - comments: Total number of comments at this moment.
  - catid: The numeric ID for the story's category
  - senderid: The numeric ID of the person who submitted the story. If anonymous submissions are allowed, the value will be 0 (zero).
  - sendernick: For convenience, the nick of the person who submitted the story. If anonymous submissions are allowed, the value will be "Anonymous" (no quotes).
  - urlname: The URL path for this story. For example, if the URL to access this story is http://sitename.corank.com/tech/story/art-tells-the-technological-future, the value of "urlname" will be "art-tells-the-technological-future" (no quotes).
  - sdate: Date when the story was posted (PST/PDT). The value is the number of seconds since 00:00:00 January 1, 1970 (Epoch).
- The value between the <link>...</link> tags is the complete URL to the original story.
- The value for the title and description tags are, well, the title and description of the story. Note that the contents of the description may use several lines, such as in:
```
			<description>This story is about nothing
as you may have guessed by now</description>
```
- The content between the tag tags are the tags assigned to the story. If no tags have been assigned, there won't be a <tags>...</tags> section.
coRank.News.GetCatItems
It returns the list of stories under a given category. The maximum number of stories to return is 100. In order to obtain the stories beyond position 100, one must use the parameters "start" and "end".
If "end" - "start" is greater than 100, the value of "end" is ignored and only the first 100 stories, starting from "start" are returned.
Parameters:

id
Category ID.

start
Start index. If ommitted, it is asusmed to be 1.

end
End index. It must be a number bigger than "start". If ommited, it is assumed to be start+100

Example Request:
To obtain the first 100 results: http://ColbieMartin.corank.com/api/coRank.News.GetCatItems/id=16&start=1&end=100

To obtain the results 100 to 150: http://ColbieMartin.corank.com/api/coRank.News.GetCatItems/id=16&start=100&end=150
Example Response:
```
<corank siteid="437">
  <cat id="2" total="300">
    <item id="231" index="1" />
    <item id="237" index="2" />
    <item id="295" index="3" />
    ...
  </cat>
</corank>
```
Response Details:
- The value for total inside the cat tag indicates the total number of stories under the given category.
- The item tags (one per story) contain the following values:
  - id: The numeric ID of the story.
  - index: The position in the results.
coRank.News.GetComments
It returns all comments posted for a given story.
Parameters:
It may take either 'id' or 'url' but not both.

id
The numeric ID for the story.

url
The URL path for the story.

Example Request:
With the numeric ID: http://ColbieMartin.corank.com/api/coRank.News.GetComments/id=771
With the URL path: http://ColbieMartin.corank.com/api/coRank.News.GetComments/url=art-tells-the-technological-future
In the second example, we're requesting the comments for the item that can be retrieved directly by visiting http://ColbieMartin.corank.com/tech/story/art-tells-the-technological-future
Example Response:
```
<corank siteid="437">
  <item id="4478" comments="12">
    <comments>
      <comment id="1" nick="joedirt"
        sdate="1170668942" rank="1,0,0,3,8"><![CDATA[Cool story]]></comment>
      <comment id="2" nick="joedirt"
        sdate="1170698547" rank="5,1,0,2,0" replyto="1"><![CDATA[It sucks]]></comment>
			...
    </comments>
  </item>
</corank>
```
Response Details:
- The item tag always includes two values.
  - id: The numeric ID of the story.
  - comments: The total number of comments to this story.
- The comment tags contains several values. All of these values appear on each 'comment' tag, except for "replyto" which will only appear if the comment is a reply to another comment:
  - id: The numeric ID of the comment.
  - nick: Nick of the person who posted the comment.
  - sdate: Date the comment was posted (PST/PDT). The value is the number of seconds since 00:00:00 January 1, 1970 (Epoch).
  - rank: The five different scores a comment may have, in this order: Agree, disagree, boring, irrelevant and troll.
  - replyto: If the comment is a reply to another comment, the numeric ID of the comment being replied to.
- Each comment tag also contains, of course, the actual comments, inside a CDATA section (the stuff that goes between the <![CDATA[ ... ]]> codes). The text for the comments may be split in several lines:
```
...
	<comments>
			<comment ...><![CDATA[This is a very
cool story]]></comment>
	</comments>
...
```
coRank.News.GetFeatured, coRank.News.GetUpcoming, coRank.News.GetTop
These calls return the latest featured stories (coRank.News.GetFeatured), latest upcoming stories (coRank.News.GetUpcoming), or top stories (coRank.News.GetTop).
The results are sorted as follows:
- coRank.News.GetFeatured: Sorted by date, latest featured stories first.
- coRank.News.GetUpcoming: Sorted by date, latest submitted stories first.
- coRank.News.GetTop: Top stories first.
The maximum number of stories to return is 100. In order to obtain the stories beyond position 100, one must use the parameters "start" and "end". If "end" - "start" is greater than 100, the value of "end" is ignored and only the first 100 stories, starting from "start" are returned.
Note that Colbie Martin only "remembers" 300 featured stories anyway, so trying to retrieve featured stories beyond position 300 will return no stories.
Parameters:

start
Start index. If ommitted, it is asusmed to be 1.

end
End index. It must be a number bigger than "start". If ommited, it is assumed to be start+100

Example Request:
To obtain the latest (up to 100) featured stories: http://ColbieMartin.corank.com/api/coRank.News.GetFeatured

To obtain the last 20 to 40 upcoming stories: http://ColbieMartin.corank.com/api/coRank.News.GetUpcoming/start=20&end=40

To obtain the top 30 stories: http://ColbieMartin.corank.com/api/coRank.News.GetTop/end=20
Example Responses:
For coRank.News.GetFeatured:
```
<corank siteid="437">
  <featured>
    <item id="231" index="1" />
    <item id="237" index="2" />
    <item id="295" index="3" />
    ...
  </featured>
</corank>
```
For coRank.News.GetUpcoming:
```
<corank siteid="437">
  <upcoming>
    <item id="231" index="1" />
    <item id="237" index="2" />
    <item id="295" index="3" />
    ...
  </upcoming>
</corank>
```
For coRank.News.GetTop:
```
<corank siteid="437">
  <top>
    <item id="231" index="1" />
    <item id="237" index="2" />
    <item id="295" index="3" />
    ...
  </top>
</corank>
```
Response Details:
Responses for all three calls are identical except for the identifying tags (featured, upcoming and top).
- The item tags (one per story) contain the following values:
  - id: The numeric ID of the story.
  - index: The position in the results.

Users level API calls

All user level calls also assume the site you're referring to is the one from where you're running the API call. This is important because a user will have different stats depending on the coRank site you're querying.

coRank.User.GetProfile
Returns a wealth of information about any given user.
Parameters: It may take either 'id' or 'nick' but not both.

id
The user numeric ID.

nick
The user nickname .

Example Requests:
With the user ID: http://ColbieMartin.corank.com/api/coRank.User.GetProfile/id=771
With the user nick: http://ColbieMartin.corank.com/api/coRank.User.GetProfile/nick=joesmith
Example Response:
```
<corank siteid="437">
	<user id="3345" nick="joesmith" sources="12" fans="34" pviews="67" grank="3" mrank="2">
		<name>Joe Smith</name>
		<location>US</location>
		<blog>http://myblogishere.example.com/</blog>
		<about><![CDATA[I'm into whatever I like]]></about>
		<stories submitted="22" vup="3344" vdown="11" fav="12" />
	</user>
</corank>
```
Response Details:
- The user tag always includes these values.
  - id: The numeric ID for the user
  - nick: Username
  - sources: Number of sources this user has
  - fans: Number of fans
  - pviews: Number of profile views
  - grank: Global ranking position
  - mrank: Monthly ranking position
- The stories tag is always returned, even if all values in it are zero. It will always include:
  - submitted: Number of stories submitted
  - vup: Number of positive votes
  - vdown: Number of negative votes
  - fav: Number of stories the user has saved in his/her favorites
The following values will be present in the response only if they have been completed by the user:
- name: The real user name
- location: The 2-letter ISO 3161 Country codes
- blog: Blog URL
- about: The "About me" text. It's in a CDATA section and the text may be split in several lines:
```
...
	<about><![CDATA[I'm into whatever
I like]]></about>
...
```
coRank.User.GetSubmitted, coRank.User.GetVoted
The above calls return the list of stories a user has submitted (coRank.User.GetSubmitted) or voted (coRank.User.GetVoted).
The maximum number of stories to return is 100. In order to obtain the stories beyond position 100, one must use the parameters "start" and "end".
If "end" - "start" is greater than 100, the value of "end" is ignored and only the first 100 stories, starting from "start" are returned.
The results are sorted by date, latest submitted/voted first. You'll be able to specify different sorting orders in an upcoming version of the API.
Parameters:
To identify the user, you must include either 'id' or 'nick' but not both.

id
The user numeric ID.

nick
The user nickname.

start
Start index. If ommitted, it is asusmed to be 1.

end
End index. It must be a number bigger than "start". If ommited, it is assumed to be start+100

Example Request:
To obtain the last 100 stories submitted by user ID 16: http://ColbieMartin.corank.com/api/coRank.User.GetSubmitted/id=16&start=1&end=100

To obtain the last 100 to 150 stories voted by Joe: http://ColbieMartin.corank.com/api/coRank.User.GetVoted/nick=joe&start=100&end=150
Example Responses:
For coRank.User.GetSubmitted:
```
<corank siteid="437">
	<user id="16" nick="joe" total="300">
		<item id="231" index="1" />
		<item id="237" index="2" />
		<item id="295" index="3" />
		...
	</user>
</corank>
```
For coRank.User.GetVoted:
```
<corank siteid="437">
	<user id="16" nick="joe" total="300">
		<item id="231" vote="+" index="1" />
		<item id="237" vote="+" index="2" />
		<item id="295" vote="-" index="3" />
		...
	</user>
</corank>
```
Response Details:
- The user tag (only one included in the results) always contains the following values:
  - total: The total number of stories submitted/voted by this user.
  - id: The user numeric ID.
  - nick: The username.
- The item tags (one per story) contain the following values:
  - id: The numeric ID of the story.
  - index: The position in the results.
  - vote: (Only for coRank.User.GetVoted) The vote. + for a positive vote and - for a negative vote
coRank.User.GetSources
The above calls return the list of sources a particular user has.
The maximum number of users to return is 100. In order to obtain the users beyond position 100, one must use the parameters "start" and "end".
If "end" - "start" is greater than 100, the value of "end" is ignored and only the first 100 sources, starting from "start" are returned.
The results are sorted in the order the users were added as sources. You'll be able to specify different sorting orders in an upcoming version of the API.
Parameters:
To identify the user, you must include either 'id' or 'nick' but not both.

id
The user numeric ID.

nick
The user nickname.

start
Start index. If ommitted, it is asusmed to be 1.

end
End index. It must be a number bigger than "start". If ommited, it is assumed to be start+100

Example Request:
To obtain the first 100 sources of user ID 16: http://ColbieMartin.corank.com/api/coRank.User.GetSources/id=16&start=1&end=100

To obtain the last 100 to 150 Joe's sources: http://ColbieMartin.corank.com/api/coRank.User.GetSources/nick=joe&start=100&end=150
Example Response:
```
<corank siteid="437">
	<user id="16" nick="joe" total="98">
		<source id="231" weight="100" index="1" />
		<source id="237" weight="100" index="2" />
		<source id="295" weight="50" index="3" />
		...
	</user>
</corank>
```
Response Details:
- The user tag (only one included in the results) always contains the following values:
  - total: The total number of sources this user has.
  - id: The user numeric ID.
  - nick: The username.
- The source tags (one per source) contain the following values:
  - id: The numeric ID of the source (user).
  - weight: The weight given by the user to the source.
  - index: The position in the results.
coRank.User.GetFans
Returns the list of fans of a particular user.
The maximum number of users to return is 100. In order to obtain the fans beyond position 100, one must use the parameters "start" and "end".
If "end" - "start" is greater than 100, the value of "end" is ignored and only the first 100 fans, starting from "start" are returned.
The results are sorted in the order the fans added the user as their source. You'll be able to specify different sorting orders in an upcoming version of the API.
Parameters:
To identify the user, you must include either 'id' or 'nick' but not both.

id
The user numeric ID.

nick
The user nickname.

start
Start index. If ommitted, it is asusmed to be 1.

end
End index. It must be a number bigger than "start". If ommited, it is assumed to be start+100

Example Request:
To obtain the first 100 fans of user ID 16: http://ColbieMartin.corank.com/api/coRank.User.GetFans/id=16&start=1&end=100

To obtain the first 100 to 150 Joe's fans: http://ColbieMartin.corank.com/api/coRank.User.GetFans/nick=joe&start=100&end=150
Example Response:
```
<corank siteid="437">
	<user id="16" nick="joe" total="98">
		<fan id="231" index="1" />
		<fan id="237" index="2" />
		<fan id="295" index="3" />
		...
	</user>
</corank>
```
Response Details:
- The user tag (only one included in the results) always contains the following values:
  - total: The total number of fans this user has.
  - id: The user numeric ID.
  - nick: The username.
- The fan tags (one per user) contain the following values:
  - id: The numeric ID of the fan (user).
  - index: The position in the results.
coRank.User.GetLikeMinded
The above calls return the list of like-minded users for a particular user.
The results are sorted by affinitym that is, users that are more like-minded will appear first. The maximum number of like-minded users returned is 50. You cannot retrieve like-minded users beyond the 50th most like-minded user.
Parameters:
To identify the user, you must include either 'id' or 'nick' but not both.

id
The user numeric ID.

nick
The user nickname.

Example Request:
http://ColbieMartin.corank.com/api/coRank.User.GetLikeMinded/id=16

http://ColbieMartin.corank.com/api/coRank.User.GetLikeMinded/nick=joe
Example Response:
```
<corank siteid="437">
	<user id="16" nick="joe" total="23">
		<match id="231" index="1" />
		<match id="237" index="2" />
		<match id="295" index="3" />
		...
	</user>
</corank>
```
NOTE: There's additional info usually associated to like-minded users (agreement/disagreement in votes, etc). That info is not yet supplied by the API but it will be included in a future version of the API.
Response Details:
- The user tag (only one included in the results) always contains the following values:
  - total: The total number of like-minded users included in the response.
  - id: The user numeric ID.
  - nick: The username.
- The match tags (one per user) contain the following values:
  - id: The numeric ID of the like-minded user.
  - index: The position in the results.

Error Codes

When an API call cannot be completed or is unable to return meaningful results, an error code is returned instead.

Example Response:

<rsp stat="fail">
	<err code="1" msg="Method missing" />
</rsp>

Response Details:

The err tag always contains the two following values:
- code: A numeric code.
- msg: A short, descriptive message of the error.

The current numeric codes and their equivalent messages are:

1 - Method missing
2 - Invalid API key
3 - Missing parameters
4 - The end parameter is smaller than the start parameter
5 - No story found.
6 - No stories found.
7 - No user found.
8 - No users found.
8 - Daily API calls limit reached
9 - User exists but has never used this site.
<< Go back

Home | Tools | Help & FAQ | About Colbie Martin | Contact us