|
Featured Applications Here are some applications that were developed using the phonezap API.
|
Phonezap API Reference
interact with phonezap, your imagination is the limit!
Overview
Developers can create third party applications using our API. Our API is open and is free to use. Most of our API methods do not require any special developer keys or tokens, so anyone can start using our API right away.
Requests are performed using HTTP/1.1 GET and HTTP/1.1 POST, and responses are delivered in XML 1.0, using UTF-8 Encoding.
Below you will find examples of requests and all the available methods that are currently available.
Request Format
The following is the general format of the HTTP Request, unless otherwise stated. Note that the users password must be hashed with SHA1 when it is transmitted.
http://user:sha1(pass)@phonezap.com/api/public/methodName?param1=value1¶m2=value2 .....
Methods
The following methods are currently available. Methods may be periodically changed or modified from time to time if new features are added. Be sure to check back here for updates.
authenticate
This method is used to determine if a given username and password is valid. Parameters: This method requires no parameters, therefore it can be requested by simply sending: Example Request: http://user:sha1(pass)@phonezap.com/api/public/authenticate Response:
Code will return OK if authentication succeeds, otherwise you will receive and HTTP 401 Response Code.
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Code>OK</Code>
<Message></Message>
<Data>'Authentication Successful'</Data>
</Response>
newUser
This method is used to create a new phonezap user account from within your application. If the user picture (avatar) is being sent, then the form post *must* be in multipart/form-data format This method requires an appId to be provided prior to use. Please contact us if you wish to use this method. Parameters: The parameters marked as Required must be present. All the other parameters are optional, but it is encouraged to request all the paramaters from the user and pass them all. This method uses the following parameters:
username - (Required) - The username for the account. Must be between 3-24 Characters that are alphanuemeric only (a-z, 0-9)
password - (Required) - The password for the account. Must be between 6-24 characters.
appid - (Required) - Your developer application ID, please contact us if you do not have one.
email - (Optional) - An email address for the account
location - (Optional) - In generla, users should be asked to provide 'City, Country', but any input will be accepted such as "The Moon", or 'Nowhere'
aboutme - (Optional) - Users may provide a short bio of themselves
interests - (Optional) - Users may provide a couple things they're interested in or enjoy
avatar - (Optional) - Raq JPEG data for the user's profile picture (avatar). Image should be square, and 95x95 pixels.
Example Request:
http://phonezap.com/api/public/newUser?username=newuser&password=123456&email=user@email.com&location=new%20york&....
Response:
Code will contain OK if user was created successfully. If anything else, please check the message field in the xml, the return values will indicate which field has an error, and return the data we received.
Example response for duplicate username:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Code>ERROR</Code>
<Message><username message="Taken">phonezap</username</Message>
</Response>
postUpdate
This method is used to post a new picture, or text-only message (blog post) to the user's account. We will not accept empty posts.
If sending a image with the post, it must be sent as a multipart/form-data POST to http://phonezap.com/api/public/postUpdate Parameters: This method uses the following parameters: message - The message to post to the site (if no image is present the message will be posted as a blog post)
imagedata - Binary data for a jpeg image, of any size, but we recommend at least 640x480 resolution
deviceType - Possible values = iPhone, WindowsMobile, JavaMobile, Blackberry, Palm, Other
location - Users should be asked to provide the location in google maps format i.e. street, city, province, country. however, this is not error checked, we will accept blank location or invalid locations. If location is blank and geoposition is provided, we will try to populate this on the server.
lat - If your device has GPS or location capabilities, pass the latitude.
long - If your device has GPS or location capabilities, pass the longditude.
appID - Please contact us to acquire an appID for your application. This will let people see the name of your application when items are posted with it.
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/postUpdate?message="hello%20world!"&location="Tokyo,%20Japan"&geoposition=35.683100,139.809000&appid=2938272
Response:
Code will contain OK if the data was valid and accepted. Data field will contain xml node PostUrl which will contain the url to the newly posted item, in the case of an image a confirmation of that will be provided by means of MediaType xml node which will contain "Image". If an error has occured, the Code will contain ERROR and the message field will explain the error. Possible error values are:
- No message or picture supplied
- System Error
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Code>OK</Code>
<Data>
<PostUrl>http://phonezap.com/phonezap/pictures/123123</PostUrl>
<MediaType>Image</MediaType>
</Data>
</Response>
getMessageCount
This method returns the messages available to said user, followed by a starting messageid and a trailing messageid. The messageid can be used at any time to retrieve new, or old messages using the getMessages api call. Its recommended that the messageid be stored for the user, and can be used periodically to check for new messages. If the application is a new setup for a user, we recommend requesting the messagecount with messageid=0 to retrieve the initial indexes (either the first, or the last).
Parameters:
This method takes one parameter
| Parameter | Required | Description |
| messageid | Y | The messageid to retrieve the message counts |
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/getMessageCount?messageid=0
Response:
Code will contain OK, and the Data field will contain an Xml Nodes that contain:
| Field |
Description |
| TotalMessages | The total number of messages for this user |
| MessagesSinceIndex | The total number of new messages, since the index provided |
| FirstMessageID | The index of the first message |
| MostRecentMessageID | The index of the last message |
Example response:
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Code>OK</Code>
<Data>
<MessageInfo>
<Info>
<TotalMessages>44</TotalMessages>
<MessagesSinceIndex>44</MessagesSinceIndex>
<FirstMessageID>222</FirstMessageID>
<MostRecentMessageID>365686</MostRecentMessageID>
</Info>
</MessageInfo>
</Data>
</Response>
getMesssages
This method returns messages sent to the user, using an messageid for positioning and a count for the number of messages to retrieve. This method can be used in conjunction with the api call getMessageCount.
Parameters:
This method takes two parameters
| Parameter | Required | Description |
| messageid | Y | The messageid to start the retrieval of messages |
| count | Y | The number of messages to retrieve forward, or backward. A negative count retrieves messages before the index (older messages). A positive count retrieves messages after the index (newer messages) |
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/getMessages?messageid=365686&count=20
Response:
Code will contain OK, and the Data field will contain an Xml Nodes that contain:
| Field |
Description |
| MessageID | The messageID for this message |
| Date | The date of the message. The date is in ISO-8860 format |
| TimeAgo | English readable time lapse since the message was posted (eg: 24 minutes ago) |
| Message | The full message |
| SentByUsername | Username of the poster |
| AvatarUrl | Url to the avatar for the poster |
| ReplyUrl | Url that can be used to send the user to a page to reply to this item |
Example response:
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Code>OK</Code>
<Data>
<Messages>
<Message>
<MessageID>365690</MessageID>
<Date>2008-04-10T18:58:55.487-07:00</Date>
<TimeAgo>26 days ago</TimeAgo>
<Message>cool phonezap page!</Message>
<SentByUsername>phonezap</SentByUsername>
<AvatarUrl>http://phonezap.com/Site/View.aspx?avatar=0</AvatarUrl>
<ReplyUrl>http://m.phonezap.com/MessageReply.aspx?mlid=365690&password=2B76BC65A367AE587B4D60D0C827840FFFF61EFA</ReplyUrl>
</Message>
<Message>
<MessageID>365751</MessageID>
<Date>2008-04-11T18:58:55.487-07:00</Date>
<TimeAgo>27 days ago</TimeAgo>
<MessageType>Message</MessageType>
<Message>cool phonezap page!</Message>
<SentByUsername>phonezap</SentByUsername>
<AvatarUrl>http://phonezap.com/Site/View.aspx?avatar=0</AvatarUrl>
<ReplyUrl>http://m.phonezap.com/MessageReply.aspx?mlid=365751&password=2B76BC65A367AE587B4D60D0C827840FFFF61EFA</ReplyUrl>
</Message>
</Messages>
</Data>
</Response>
Note: If you request 20 messages by specifiying count=20, and there are less than 20 messages available, you will only be returned what is available. We recommend saving the last message's Index and use that for subsequent calls to getMessages, or getMessageCounts
getCommentCount
Like getMessageCount, this method returns the comments sent to said user's zaps, followed by a starting commentid and a trailing commentid. The commentid can be used at any time to retrieve new, or old comments using the getComments api call. Its recommended that the commentid be stored for the user, and can be used periodically to check for new comments. If the application is a new setup for a user, we recommend requesting the commentcount with commentid=0 to retrieve the initial indexes (either the first, or the last).
Parameters:
This method takes one parameter
| Parameter | Required | Description |
| commentid | Y | The commenid to retrieve the comment counts |
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/getCommentCount?commentid=0
Response:
Code will contain OK, and the Data field will contain an Xml Nodes that contain:
| Field |
Description |
| TotalComments | The total number of comments sent to this user |
| CommentsSince | The total number of new comments, since the commentid provided |
| FirstCommentID | The commentid of the first message |
| MostRecentCommentID | The commentid of the last message |
Example response:
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Code>OK</Code>
<Data>
<CommentsInfo>
<Info>
<TotalComments>62</TotalComments>
<CommentsSince>62</CommentsSince>
<FirstCommentID>1</FirstCommentID>
<MostRecentCommentID>136620MostRecentCommentID
</Info></CommentsInfo>
</Data>
</Response>
getComments
This method returns comments sent to the user's zaps, using an commentid to position the comments to get and a count to return a number of comments. This method can be used in conjunction with the api call getCommentCount.
Parameters:
This method takes two parameters
| Parameter | Required | Description |
| commentid | Y | The commentod to start the retrieval of comments |
| count | Y | The number of comments to retrieve forward, or backward. A negative count retrieves comments before the index (older messages). A positive count retrieves comments after the index (newer messages) |
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/getComments?commentid=136620&count=20
Response:
Code will contain OK, and the Data field will contain an Xml Nodes that contain:
| Field |
Description |
| CommentID | The commentid for this comment |
| Date | The date of the comment. The date is in ISO-8860 format |
| TimeAgo | English readable time lapse since the message was posted (eg: 24 minutes ago) |
| Comment | The full comment |
| SentByUsername | Username of the poster |
| ImageUrl | Url to the image being commented on |
| AvatarUrl | Url to the avatar for the poster |
| ReplyUrl | Url that can be used to send the user to a page to reply to this item |
Example response:
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Code>OK</Code>
<Data>
<Comments>
<Comment>
<CommentID>136623</CommentID>
<Date>2008-04-10T18:58:55.487-07:00</Date>
<TimeAgo>26 days ago</TimeAgo>
<Comment>Nice Car!</Comment>
<SentByUsername>phonezap</SentByUsername>
<ImageUrl>http://m.phonezap.com/z/1000218</ImageUrl>
<AvatarUrl>http://phonezap.com/Site/View.aspx?avatar=0</AvatarUrl>
<ReplyUrl>http://m.phonezap.com/z/1000218?userid=phonezap&password=2B76BC65A367AE587B4D60D0C8278403F4F61EFA</ReplyUrl>
</Comment>
<Comment>
<CommentID>136677</CommentID>
<Date>2008-04-11T18:58:55.487-07:00</Date>
<TimeAgo>27 days ago</TimeAgo>
<Comment>Ya Really Nice Car!</Comment>
<SentByUsername>phonezap</SentByUsername>
<ImageUrl>http://m.phonezap.com/z/1000218</ImageUrl>
<AvatarUrl>http://phonezap.com/Site/View.aspx?avatar=0</AvatarUrl>
<ReplyUrl>http://m.phonezap.com/z/1000218?userid=phonezap&password=2B76BC65A367AE587B4D60D0C8278403F4F61EFA</ReplyUrl>
</Comment>
</Messages>
</Data>
</Response>
Note: If you request 20 comments by specifiying count=20, and there are less than 20 comments available, you will only be returned what is available. We recommend saving the last message's Index and use that for subsequent calls to getComments or getCommentCounts. Note that this index is different, and seperate to the index provided by getMessages and getMessageCount
getPrefs
This method returns some (or all) of the preferences for the user's account.
Parameters:
This method requires no parameters.
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/getPrefs
Response:
Code will contain OK and the Data node will contain the following Nodes
| Node | Description |
| UserInfo | Master xmlnode that contains information about the user |
| AlertPrefs | Master xmlnode that contains the users alert preferences |
| FriendAlert | Master xmlnode that contains the users friends alert preferences |
The UserInfo node contains the following Nodes
| Node | Description |
| Location | Location of the user |
| Interests | Users interests |
| AboutMe | Short bio for the user |
| Users current email address | |
| CurrentAvatarUrl | Url to the current avatar for the user |
The AlertPrefs node contains the following Nodes
| Node | Description |
| SendSMSWhenComment | Set to 1 if the user wants an SMS sent to them when they receive a comment on their zaps. 0 if they do not |
| SendSMSWhenMessage | Set to 1 if the user wants and SMS sent to them when they receive a message on their site. 0 if they do not |
The FriendAlert node contains the following Nodes for each friend
| Node | Description |
| Username | The friends username |
| Alert | 1 if they want an alert each time their friend posts a new zap or blog entry. 0 if they do not |
Example Response:
<?xml version="1.0" encoding="utf-8"?>
<Response>
<Code>OK</Code>
<Data>
<Preferences>
<UserInfo>
<Location>Orange, CA</Location>
<Interests>Photography, Coding!</Interests>
<AboutMe>Dub Dub</AboutMe>
<Email>jthanki@techie.org</Email>
<CurrentAvatarUrl>http://dev.phonezap.com/Site/View.aspx?avatar=24</CurrentAvatarUrl>
</UserInfo>
<AlertPrefs>
<SendSMSWhenComment>1</SendSMSWhenComment>
<SendSMSWhenMessage>1</SendSMSWhenMessage>
</AlertPrefs>
<FriendAlert>
<Username>curtwu</Username>
<Alert>1</Alert>
</FriendAlert>
<FriendAlert>
<Username>dino</Username>
<Alert>1</Alert>
</FriendAlert>
<FriendAlert>
<Username>kaushal</Username>
<Alert>1</Alert>
</FriendAlert>
<FriendAlert>
<Username>madness</Username>
<Alert>1</Alert>
</FriendAlert>
<FriendAlert>
<Username>thewitt</Username>
<Alert>1</Alert>
</FriendAlert>
</Preferences>
</Data>
</Response>
savePrefs
This method will update the users account with new saved prefs.
Parameters:
If posting a new avatar, the form post MUST be of type multipart/form-data format.
| Parameter | Required | Description |
| location | N | Location of the user |
| aboutme | N | Short bio for the user |
| interests | N | Users interests |
| N | Users new email address | |
| avatar | N | Jpeg Image data for new avatar for this user |
| SendSMSWhenComment | N | 1 if the user wants to receive an SMS when they get a new comment on their zaps |
| SendSMSWhenMessage | N | 1 if the user wants to receive an SMS when they get a new message post |
| friendX | N | CSV formatted string for user alert preferences, format is username,<1:0> (Where 1 is set if the user wants alerts from that friend) |
Example Request:
http://user:sha1(pass)@phonezap.com/api/public/savePrefs?location=Nowhere%20special&email=new@email.com
&SendSMSWhenComment=0&friend0=phonezap,1&frined1=phonezap2,0&friend2=phonezap3,0
Response:
Code will return OK if the data was parsed and saved. If an error occurs, the Message field will contain a detailed description of the error.