Upcoming API Documentation - Version 1.0

Important Note: Currently, the use of these APIs are restricted to non-commercial use only. If you'd like to use it for commercial purposes, please apply for commercial access. We grant almost every request, but just like to keep track.

<rsp stat="ok" version="1.0">
	[Data in XML format - see individual method docs]
</rsp>

<rsp stat="fail">
	<error msg="Error Message" />
<rsp>

Language Bindings and Libraries

To see if your programming language has an Upcoming API library already written, check this list of Language-Specific Libraries.

Token-Based Authentication

Certain API Methods, such as event addition, watchlist management, etc., require authentication to use and commit data in the name of an Upcoming user. Most mashups that only deal with public event data won't have to worry about authenticating, but any apps that either need to use private user data, or commit new data to Upcoming can read about our token-based authentication mechanism here.

How do I use it?

You can call the Upcoming service gateway at http://upcoming.yahooapis.com/services/rest/ with either HTTP GET or POST, along with your API Key, the method name, and any other arguments desired.

For example, here's a sample GET query (use with your API Key):

If you know how to use cURL, here's a sample POST in cURL command-line syntax (use with your API Key):

Mailing List

Developers, developers, developers! Our Yahoo! Group serves as a central place for you to communicate with us and the rest of the Upcoming developer community. You can check it out by visiting the yws-events group. Stop by and introduce yourself! Please let us know about your cool stuff using the Upcoming API. We're listening to your feedback and making improvements, and we will send out notice whenever there's a change to our API.

Methods

auth

auth.getToken [HTTP GET]
auth.checkToken [HTTP GET]

event

event.getInfo [HTTP GET]
event.add [HTTP POST]
event.edit [HTTP POST]
event.addTags [HTTP POST]
event.removeTag [HTTP POST]
event.search [HTTP GET]
event.getWatchlist [HTTP GET]
event.getGroups [HTTP GET]
event.getBestInPlace [HTTP GET]

metro

metro.getInfo [HTTP GET]
metro.getForLatLon [HTTP GET]
metro.search [HTTP GET]
metro.getMyList [HTTP GET]
metro.getList [HTTP GET]
metro.getStateList [HTTP GET]
metro.getCountryList [HTTP GET]

state

state.getInfo [HTTP GET]

country

country.getInfo [HTTP GET]

venue

venue.add [HTTP POST]
venue.edit [HTTP POST]
venue.getInfo [HTTP GET]
venue.getList [HTTP GET]
venue.search [HTTP GET]

category

category.getList [HTTP GET]

watchlist

watchlist.getList [HTTP GET]
watchlist.add [HTTP POST]
watchlist.remove [HTTP POST]

user

user.getInfo [HTTP GET]
user.getInfoByUsername [HTTP GET]
user.getInfoByEmail [HTTP GET]
user.getMetroList [HTTP GET]
user.getWatchlist [HTTP GET]

group

group.getInfo [HTTP GET]
group.getMembers [HTTP GET]
group.getEvents [HTTP GET]
group.getMyGroups [HTTP GET]
group.add [HTTP POST]
group.edit [HTTP POST]
group.join [HTTP POST]
group.leave [HTTP POST]
group.addEventTo [HTTP POST]
group.admin.removeEvent [HTTP POST]

"Powered By" Banners

Looking for a way to show off your snazzy use of the Upcoming API?
Feel free to download and re-use (but don't hot-link!) these "Powered By" banners, and link them to http://upcoming.yahoo.com, please!

Banner 1 (GIF, 200x52):  

Banner 2 (GIF, 197x27):