The First Round Capital Startup News API (Application Program Interface)
allows people to interact programmatically with First Round Capital Startup News.
The First Round Capital Startup News API is available free of charge, and it returns data generated by First Round Capital Startup News in a form that can be easily integrated into an application or a website.
This is the first version of the First Round Capital Startup News API. It provides a handful of
basic calls, but there's a lot more funtionality on the way.
At this moment the First Round Capital Startup News 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
<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.
idname is the name used in URLs for that category,
for example http://firstround.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
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://firstround.corank.com/api/coRank.News.GetItem/id=771
With the URL path: http://firstround.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://firstround.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://firstround.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.
<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://firstround.corank.com/api/coRank.News.GetCatItems/id=16&start=1&end=100
To obtain the results 100 to 150: http://firstround.corank.com/api/coRank.News.GetCatItems/id=16&start=100&end=150
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://firstround.corank.com/api/coRank.News.GetComments/id=771
With the URL path: http://firstround.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://firstround.corank.com/tech/story/art-tells-the-technological-future
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>
...
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 First Round Capital Startup News 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://firstround.corank.com/api/coRank.News.GetFeatured
To obtain the last 20 to 40 upcoming stories: http://firstround.corank.com/api/coRank.News.GetUpcoming/start=20&end=40
To obtain the top 30 stories: http://firstround.corank.com/api/coRank.News.GetTop/end=20
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://firstround.corank.com/api/coRank.User.GetProfile/id=771
With the user nick: http://firstround.corank.com/api/coRank.User.GetProfile/nick=joesmith
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://firstround.corank.com/api/coRank.User.GetSources/id=16&start=1&end=100
To obtain the last 100 to 150 Joe's sources: http://firstround.corank.com/api/coRank.User.GetSources/nick=joe&start=100&end=150
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://firstround.corank.com/api/coRank.User.GetFans/id=16&start=1&end=100
To obtain the first 100 to 150 Joe's fans: http://firstround.corank.com/api/coRank.User.GetFans/nick=joe&start=100&end=150
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.
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.
First Round Capital Startup News API