API Documentation

Software developers can use our application programming interface (API) to build applications that exchange data with Plancast programmatically.

The following documentation describes how to interface RESTfully with our API. It returns data in JSON format. For those interested in alternative formats, we've also made RSS and iCal feeds available across the site, such as on user profile and category pages.

If you have any questions, suggestions or corrections, please write to us at api@plancast.com. You can also join our Google Group to get announcements and participate in discussions with other developers.

Authentication

The API currently supports only basic access authentication and not other protocols such as oAuth (sorry). Authentication requires a particular user's username and password, which must be set beforehand even if the user originally joined Plancast by authenticating with their Facebook or Twitter account.

Rate Limits

There are no explicit rate limits placed on API usage, nor do we assign API keys. However, we do monitor usage and will intervene when service performance suffers due to an unreasonable number of requests.

Libraries

Wynn Netherland has created a Ruby wrapper and Bartek Ciszkowski has created a Python wrapper you can use. If you've created a library of your own for the Plancast API that you'd be willing to share, please let us know.

JSONP

JSONP can be attained for most methods by passing your desired callback function name as the value for the "jsonp" parameter (for example, http://api.plancast.com/02/users/search.json?q=mark&jsonp=myCallback).

Times & Time Zones

Plancast handles times and time zones for plans by storing all timestamps in UTC. This effectively means that Plancast treats a plan taking place in California at 6pm as occurring at the same time as a plan taking place at 6pm in New York or France.

If your application adjusts timestamps based on time zone offsets, you may need to recalculate the timestamp you get from, or post to, us.

Methods

Method Description
account/verify_credentials Verifies account credentials and gets information about the authenticated user
users/show Gets the details of a user
users/subscriptions Gets a user's subscriptions
users/subscribers Gets a user's subscribers
users/discover_friends Gets users who are friends of a particular user on Facebook or Twitter
users/search Searches for users by keyword
subscriptions/update Creates a subscription
subscriptions/destroy Deletes a subscription
plans/user Gets the plans of a user
plans/home Gets the plans on a user's homepage (the user's plans plus those of the user's subscriptions)
plans/show Gets the details of a plan
plans/update Creates a new plan or updates an existing plan's details
plans/attend Adds an attendance to a plan for a user
plans/destroy Deletes an attendance, and possibly its associated plan
plans/search Searches for plans by keyword
plans/parse_when Parses a datetime string and returns the result
plans/parse_where Looks up places based on a keyword string and returns the results
comments/update Creates a comment
comments/destroy Deletes a comment

account/verify_credentials

Returns information about the authenticated user. This method can be used to initially authenticate a user and verify their information.

URL: http://api.plancast.com/version/account/verify_credentials.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: true

Parameters: N/A

Example: curl --user mark http://api.plancast.com/02/account/verify_credentials.json

Response:

{
  • id: 1
  • name: Mark Hendrickson
  • username: mark
  • pic_square: http://a1.twimg.com/profile_images/743512682/nietzsche2_normal.jpg
  • location: San Francisco, CA
  • bio: Relapsed resident of the bay area
  • url: http://markmhendrickson.com
  • protected: 0
  • plans_count: 327
  • subscribers_count: 1963
  • subscriptions_count: 958
  • utc_offset: -25200
  • time_zone: America/Los_Angeles
  • facebook_id: 4600185
  • facebook_username: markmhendrickson
  • syndicate_facebook: 0
  • twitter_id: 9896832
  • twitter_username: mhendric
  • syndicate_twitter: 0
  • subscriber: 0
  • subscription: 0
  • subscription_pending: 0
  • created_at: Fri Aug 07 17:18:54 +0000 2009
  • created_since: 10 months
}

users/show

Returns information about a given user.

URL: http://api.plancast.com/version/users/show.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • user_id or username - Required - User identifier
Example: curl http://api.plancast.com/02/users/show.json?user_id=1

Response (truncated):

{
  • id: 1
  • name: Mark Hendrickson
  • username: mark
  • pic_square: http://plancast.com/uploads/pics/1_pic_square_1271972091.jpg
  • location: San Francisco, CA
  • bio: Relapsed resident of the bay area
  • url: http://ursusrex.com
  • protected: 0
  • plans_count: 291
  • subscribers_count: 1964
  • subscriptions_count: 959
  • utc_offset: -25200
  • time_zone: America/Los_Angeles
  • facebook_id: 4600185
  • facebook_username: markmhendrickson
  • syndicate_facebook: 0
  • twitter_id: 9896832
  • twitter_username: mhendric
  • syndicate_twitter: 0
  • subscriber: 0
  • subscription: 1
  • created_at: Fri Aug 07 17:18:54 +0000 2009
  • created_since: 9 months, 1 week
}

users/subscriptions

Return the users to which a given user is subscribed.

URL: http://api.plancast.com/version/users/subscriptions.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • user_id or username - Required - User identifier
  • page - Optional (default: 1) - Page number, with 25 users returned per page
Example: curl http://api.plancast.com/02/users/subscriptions.json?user_id=1

Response (truncated):

{}

users/subscribers

Return the users who are subscribed to a given user.

URL: http://api.plancast.com/version/users/subscribers.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • user_id or username - Required - User identifier
  • page - Optional (default: 1) - Page number, with 25 users returned per page
Example: curl http://api.plancast.com/02/users/subscribers.json?user_id=1

Response (truncated):

{}

users/discover_friends

Returns the users connected to the authenticated user on a given network (Facebook or Twitter)

URL: http://api.plancast.com/version/users/discover_friends.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: true

Parameters:
  • service - Required (possible values: facebook, twitter) - Whether to return friends from Facebook or Twitter
  • page - Optional (default: 1) - Page number, with 25 users returned per page
Example: curl http://api.plancast.com/02/users/discover_friends.json?service=facebook

Response (truncated):

{}

users/search

Returns up to 25 users that match the given keyword(s).

URL: http://api.plancast.com/version/users/search.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • q - Required - Keyword(s)
Example: curl http://api.plancast.com/02/users/search.json?q=mark

Response (truncated):

{}

subscriptions/update

Subscribes the authenticated user to a target user and returns information about the target user. If the target user has enabled account protection, a subscription request will be sent.

URL: http://api.plancast.com/version/subscriptions/update.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • user_id or username - Required - Identifier for the target user
Example: curl -u username:password -d "user_id=1" http://api.plancast.com/02/subscriptions/update.json

Response:

{"id":33,"name":"Peter Sauer","username":"peter","pic_square":"http:\/\/profile.ak.fbcdn.net\/v223\/268\/108\/q22411132_5249.jpg"}

subscriptions/destroy

Stops the authenticated user from subscribing to a target user and returns information about the target user

URL: http://api.plancast.com/version/subscriptions/destroy.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • user_id or username - Required - Identifier for the target user
Example: curl -u username:password -d "user_id=1" http://api.plancast.com/02/subscriptions/destroy.json

Response:

{
    "bio": "Plancast Biz Dev & Marketing", 
    "created_at": "Sat Aug 15 01:39:35 +0000 2009", 
    "created_since": "9 months", 
    "facebook_id": "22411132", 
    "facebook_username": "petersauer", 
    "id": 33, 
    "location": "Mountain View, CA", 
    "name": "Peter Sauer", 
    "pic_square": "http://profile.ak.fbcdn.net/v223/268/108/q22411132_5249.jpg", 
    "plans_count": 105, 
    "protected": 0, 
    "subscriber": 1, 
    "subscribers_count": 91, 
    "subscription": 0, 
    "subscriptions_count": 139, 
    "syndicate_facebook": 0, 
    "syndicate_twitter": 1, 
    "time_zone": "America/Los_Angeles", 
    "twitter_id": "14878399", 
    "twitter_username": "psauer", 
    "url": "http://www.petersauer.com", 
    "username": "peter", 
    "utc_offset": -25200
}

plans/user

Returns a given user's plans.

URL: http://api.plancast.com/version/plans/user.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • user_id or username - Required - User identifier
  • view_type - Optional (default: schedule) - The type of plans to return (possible values: schedule, stream, ongoing, past); see Listing View Types
  • page - Optional (default: 1) - Page number
  • count - Optional (default: 25, maximum: 100) - Number of plans per page
  • extensions - Optional (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
Example: curl http://api.plancast.com/02/plans/user.json?username=mark&count=15&extensions=place,comments,attendees

Response (truncated):

{}

plans/home

Returns plans on the session user's homepage (their own plans plus those of their subscriptions).

URL: http://api.plancast.com/version/plans/home.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: true

Parameters:
  • view_type - Optional (default: schedule) - The type of plans to return (possible values: schedule, stream, ongoing, past); see Listing View Types
  • page - Optional (default: 1) - Page number
  • count - Optional (default: 25, maximum: 100) - Number of plans per page
  • extensions - Optional (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
Example: curl http://api.plancast.com/02/plans/home.json?extensions=place,attendees,comments

Response (truncated):

{}

plans/show

Returns the details for a given plan.

URL: http://api.plancast.com/version/plans/show.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:

One of the following is required:
  • attendance_id - Required - The ID of an attendance, in base 36

    Example: For the attendance found at URL http://plancast.com/a/7vl, query http://api.plancast.com/02/plans/show.json?attendance_id=7vl

  • plan_id - The ID of a plan, in base 36

    Example: For the plan found at URL     http://plancast.com/p/enf, query http://api.plancast.com/02/plans/show.json?plan_id=enf

    See the difference between attendances and plans for more on the difference between these options.
These are optional:
  • extensions - Optional - Comma-delimited list of extended data types you want (possible values: attendees, comments, place); omitted by default to minimize the size of the response
Example: curl http://api.plancast.com/02/plans/show.json?attendance_id=7vl&extensions=place,attendees,comments

Response (truncated):

{}
#

plans/update

Creates a new plan or updates the details of an existing plan. Returns up-to-date information about the plan in either case.

URL: http://api.plancast.com/version/plans/update.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • what - Required - Brief descriptor of the plan
  • when - Required - String descriptor of plan's date/time; we'll take this and parse it into timestamps for you. You're highly recommended to use plans/parse_when to verify that the string is parseable first
  • where - Required - String descriptor of the plan's location
  • place_id - Optional but highly recommended - ID of a canonical place record retrieved using plans/parse_where
  • external_url - Optional - URL for more information about the plan elsewhere
  • description - Optional - Longer, more free-form descriptor of the plan
  • syndicate_facebook - Optional (default: user's default) - Whether to syndicate the plan to Facebook, if authorization is available (only effective for new plans)
  • syndicate_twitter - Optional (default: user's default) - Whether to syndicate the plan to Twitter, if authorization is available (only effective for new plans)
  • plan_id or attendance_id - Optional - Base-36 ID of an existing plan or attendance; provide this if you'd like to update a plan instead of creating a new one
Example: curl -u username:password -d "what=grabbing%20drinks&when=tonight&where=rudys&place_id=4" http://api.plancast.com/02/plans/update.json

Response:

{}

plans/attend

Adds an attendance for a particular plan for the authenticated user and returns information about it.

URL: http://api.plancast.com/version/plans/attend.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • plan_id or attendance_id - Optional - Base-36 ID of plan or existing attendance for a plan
  • syndicate_facebook - Optional (default: user's default) - Whether to syndicate the plan to Facebook, if authorization is available
  • syndicate_twitter - Optional (default: user's default) - Whether to syndicate the plan to Twitter, if authorization is available
Example: curl -u username:password -d "plan_id=12ia&syndicate_twitter=true" http://api.plancast.com/02/plans/attend.json

Response:

{
  • attendance_url: http://plancast.com/a/7vl
  • attendance_id: 7vl
  • attendance_created_at: Thu Jan 14 23:40:49 +0000 2010
  • attendance_created_since: 3 months, 4 weeks
  • attendee: {}
  • plan_url: http://plancast.com/p/4im
  • plan_id: 4im
  • plan_created_at: Thu Jan 14 21:46:10 +0000 2010
  • plan_created_since: 3 months, 4 weeks
  • creator: {}
  • text: #plan The Future of Money and Technology Summit (Hotel Kabuki) Mon, Apr 26, 2010 http://plancast.com/a/7vl
  • what: The Future of Money and Technology Summit
  • when: Monday, April 26, 2010
  • where: Hotel Kabuki
  • place: null
  • start: 1272240000
  • stop: 1272326400
  • external_url: null
  • description: null
  • is_attending: 1
  • attendees_count: 38
  • attendees: null
  • comments_num: 6
  • comments: null
}

plans/destroy

Deletes an attendance for the authenticated user and returns its previous information.

If there is more than one attendance associated with the related plan, the plan itself will not get deleted. However, if this is the only attendance associated with it, the plan will get deleted automatically as well.

URL: http://api.plancast.com/version/plans/destroy.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • plan_id or attendance_id - Optional - Base-36 ID of plan or attendance
Example: curl -u username:password -d "attendance_id=12ia" http://api.plancast.com/02/plans/destroy.json

Response:

{
  • attendance_url: http://plancast.com/a/7vl
  • attendance_id: 7vl
  • attendance_created_at: Thu Jan 14 23:40:49 +0000 2010
  • attendance_created_since: 3 months, 4 weeks
  • attendee: {}
  • plan_url: http://plancast.com/p/4im
  • plan_id: 4im
  • plan_created_at: Thu Jan 14 21:46:10 +0000 2010
  • plan_created_since: 3 months, 4 weeks
  • creator: {}
  • text: #plan The Future of Money and Technology Summit (Hotel Kabuki) Mon, Apr 26, 2010 http://plancast.com/a/7vl
  • what: The Future of Money and Technology Summit
  • when: Monday, April 26, 2010
  • where: Hotel Kabuki
  • place: null
  • start: 1272240000
  • stop: 1272326400
  • external_url: null
  • description: null
  • is_attending: 1
  • attendees_count: 38
  • attendees: null
  • comments_num: 6
  • comments: null
}

plans/search

Returns up to 25 plans that match the given keyword(s).

URL: http://api.plancast.com/version/plans/search.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: false

Parameters:
  • q - Required - Keyword(s)
  • extensions - Optional (possible values: attendees, comments, place) - Comma-delimited list of extended data types you want; omitted by default to minimize the size of the response
Example: curl http://api.plancast.com/02/plans/search.json?q=party

Response (truncated):

{}

plans/parse_when

Attempts to parse a string for datetime information and returns the result if successful. Use this to verify a "when" string before submitting a new plan with plans/update.

URL: http://api.plancast.com/version/plans/parse_when.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: true

Parameters:
  • when - Required - The string to parse
Example: curl http://api.plancast.com/02/plans/parse_when.json?when=next%20friday

Response:

{
  • string: Friday, May 14, 2010
  • start: 1273795200
  • stop: 1273881600
}

plans/parse_where

Looks up places based on a keyword string and returns matches. Use this to get a place ID from a "where" string before submitting a new plan with plans/update.

URL: http://api.plancast.com/version/plans/parse_where.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): GET

Requires authentication: true

Parameters:
  • where - Required - The keyword string
Example: curl http://api.plancast.com/02/plans/parse_where.json?where=london

Response:

[]

comments/update

Creates a new comment on a plan and returns information about it.

URL: http://api.plancast.com/version/comments/update.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • content - Required - Content of comment
  • plan_id or attendance_id - Required - ID of plan or attendance
Example: curl -u username:password -d "content=hello%20world&attendance_id=2xlm" http://api.plancast.com/02/comments/update.json

Response:

{"id":7513,"content":"hello world","user":{"id":1,"name":"Mark Hendrickson","username":"mark","pic_square":"http:\/\/plancast.com\/uploads\/pics\/1_pic_square_1271972091.jpg"},"created_at":"Fri May 14 06:47:32 +0000 2010","created_since":"0 minutes"}

comments/destroy

Deletes a comment for the authenticated user and returns its previous information.

URL: http://api.plancast.com/version/comments/destroy.format

Supported in version(s): 02

Supported return format(s): json

Supported HTTP method(s): POST

Requires authentication: true

Parameters:
  • comment_id - Optional - Comment ID
Example: curl -u username:password -d "comment_id=7511" http://api.plancast.com/02/comments/destroy.json

Response:
{"id":7513,"content":"hello world","user":{"id":1,"name":"Mark Hendrickson","username":"mark","pic_square":"http:\/\/plancast.com\/uploads\/pics\/1_pic_square_1271972091.jpg"},"created_at":"Fri May 14 06:47:32 +0000 2010","created_since":"5 minutes"}

Plans vs. Attendances

Plancast stores two related but importantly different types of information: plans and attendances.

A plan is something that will take place in the future. As such, it contains information about what will take place, when, and where. It also contains information about the user who originally shared it. An attendance is a relationship between a user and a plan that indicates that a particular user intends to participate in a particular plan. As such, it contains merely a user ID and a plan ID.

A few things to note about plans and attendances:

  • When a user submits a new plan to the site, both a plan and an attendance are generated. The plan stores the user's ID as its creator and the attendance stores the user's ID as someone who intends to do the plan

  • When other users attend this existing plan (on the site, by usually hitting the "Count Me In" button), new attendances are created for them that relate their user IDs back to the original plan ID, since they now share the same plan. No new plans are created.

  • When you view a plan on the website (e.g. http://plancast.com/p/3wmr/sf-106-miles-meetup), the site loads information about a plan and its corresponding attendees. The ID of the plan is shown near or at the end of the URL. In this example, the plan ID is "3wmr". It has numbers and letters because it's base 36-encoded for shortening purposes. Base 36 is used exclusively for representing plan and attendance IDs in the API; don't try to use base 10 for plans or attendances because they won't work even though other entities, like comments and places, have their IDs represented in base 10.

When using plans/show, you can pass either a plan_id or an attendance_id. The information that's returned is largely the same. However, if you pass an attendance_id, information about a particular attendance will be returned along with all the other information about the plan. Whether you pass an attendance_id or a plan_id depends on whether you care to distinguish one attendee of a plan from the others.

Listing View Types

When plans are pulled using any of several methods, such as plans/home, just which plans are pulled can be specified with the "view_type" parameter. There are four different view types, and it's important to understand how they differ so you get the plans you want.

  • upcoming - returns upcoming plans in chronological order. Each plan with have a "group" attribute which indicates which time grouping the plan belongs to (e.g. "next week").

  • stream - returns plans in reverse chronological order by the time they were added to the system. Use this type to get the "most recently shared" plans.

  • ongoing - returns multi-day plans that are currently ongoing, which means they started before today and have not ended yet. These are omitted from the schedule view type.

  • past - returns plans that have already transpired, in reverse chronological order. Use this type to get an archive of past plans.