API Usage Guide
The following section describes the HTTP requests that can be made to the SailBlogs server, and the XML response that is returned.
Contents |
Base URL
All calls to the SailBlogs API will be made to the following URL:
http://www.sailblogs.com/api/sbapi.php
URL Parameters
auth
Authorization key. This is REQUIRED for all API calls.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,
dt
Datatype indicator. This tells the API what kind of information you're requesting. Possible values are:
- test
- blog
- items
- contents
- comments
- msgID
- curxp
- curpc
- pcID
dt=test
Returns some information about the authorized user. This is a good way to test authorization.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=test
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<user>
<blogID>8890</blogID>
<blogTitle>Sailblogs Demo</blogTitle>
<blogDir>sailblogsdemo</blogDir>
<blogURL>http://www.sailblogs.com/member/sailblogsdemo</blogURL>
<altTitle>Demo</altTitle>
<avatarMicro>mt_sb2w958s.jpg</avatarMicro>
<xpTeamID>776</xpTeamID>
</user>
</xjournal>
dt=blog
Returns blog post information for the authorized user.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<entry>
<msgID>114806</msgID>
<postDate>2009-09-29 11:09:37</postDate>
<title><![CDATA[This is test entry 3 with a lat/long included]]></title>
<location><![CDATA[Minneapolis]]></location>
<author><![CDATA[]]></author>
<imageFile/>
<thumbnail/>
<teaser><![CDATA[
This is a blog post that includes a lat/long reference and a youtube video:
[%youtube*http://www.youtube.com/watch?v=-lriRLdiAQE%v]
Line below video...
]]></teaser>
<body>![CDATA[
This is a blog post that includes a lat/long reference and a youtube video:
[%youtube*http://www.youtube.com/watch?v=-lriRLdiAQE%v]
Line below video...
]]></body>
<comments>0</comments>
<nextmsg/>
<prevmsg/>
<latitude>44 57.22'N</latitude>
<longitude>193 22.36'W</longitude>
<declat>44.9537</declat>
<declong>-193.3727</declong>
</entry>
</xjournal>
If the items parameter is included, the system will return the number of blog posts requested:
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=blog&items=3
The above will return the three most recent entries.
dt=contents
Returns the table of contents for a particular blog:
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=contents
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<entry>
<msgID>114806</msgID>
<postDate>2009-09-29 11:09:37</postDate>
<title>This is test entry 3 with a lat/long included</title>
<location>Minneapolis</location>
<author></author>
<imageFile/>
<display>1</display>
</entry>
<entry>
<msgID>114804</msgID>
<postDate>2009-09-28 11:06:19</postDate>
<title>This is entry number 2</title>
<location>Minneapolis</location>
<author>Tim</author>
<imageFile/>
<display>1</display>
</entry>
<entry>
<msgID>103152</msgID>
<postDate>2009-09-27 10:50:36</postDate>
<title>This is my first entry</title>
<location></location>
<author></author>
<imageFile>p1010001_scale.jpg</imageFile>
<display>1</display>
</entry>
</xjournal>
dt=comments
Also requires the msgID parameter. Will return the comments available for a particular blog post.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=comments&msgID=103152
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<comment>
<msgID>103152</msgID>
<blogID>8890</blogID>
<posterName>Tim Harincar</posterName>
<posterEmail>demo@sailblogs.com</posterEmail>
<posterIP>207.250.230.131</posterIP>
<comments>this is a test comment</comments>
<postDate>2010-01-19 10:48:07</postDate>
<display>1</display>
<xj_ownerID>8887</xj_ownerID>
</comment>
</xjournal>
There will be a "comment" block for each comment added to a particular post. If the msgID parameter is not included, the system will return an error message.
dt=curxp
dt=allxp
Will return current XPlot position information available for the authorized user. curxp returns the current position only, allxp returns ALL of the position points for a user as "position" elements in the XML file.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curxp
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<position>
<posID>36846</posID>
<latitude>44 12.57'N</latitude>
<longitude>-117.2075</longitude>
<declat>44.2095</declat>
<declong>-117.0035</declong>
<plotTime>2010-01-19 16:24:36</plotTime>
<course/>
<speed/>
<pData1/>
<pData2/>
<pData3/>
<blogID/>
<teamID>776</teamID>
<mapID>43</mapID>
<xj_msgID>0</xj_msgID>
</position>
</xjournal>
dt=curpc
Also requires the pcID parameter. Will return the latest podcast information for the authorized user.
http://www.sailblogs.com/api/sbapi.php?auth=ZGVtb0BzYWlsYmxvZ3MuY29tOmxhbmRyMHZlcg,,&dt=curpc&pcID=1
Output:
<xjournal>
<api_res>0</api_res>
<api_res_msg>Ok</api_res_msg>
<pcentry>
<mp3ID>371</mp3ID>
<blogID>158</blogID>
<podcastID>1</podcastID>
<mp3File>b158_1262854986.mp3</mp3File>
<mp3Date>2010-01-07 03:03:15</mp3Date>
<display>1</display>
</pcentry>
</xjournal>
There will be a "pcentry" block for each entry added to a particular podcast.
Errors
Errors are also returned via XML. An error includes the error number, and a message (this allows developers to create custom error messages). An api_res value greater than zero indicates an error.
<xjournal> <api_res>11</api_res> <api_res_msg>No comments for this entry.</api_res_msg> </xjournal>
