Packagecom.yahoo.webapis.upcoming
Classpublic class UpcomingService
InheritanceUpcomingService Inheritance flash.events.EventDispatcher

Yahoo! Upcoming.org API Service Class. This class is the starting point for the Upcoming.org AS3 Library. It provides the API and user authentication mechanisms, and a number of functions for retrieving Upcoming.org data.


Public Properties
 PropertyDefined by
  api_id : String
The API key currently associated with this instance of UpcomingService.
UpcomingService
  api_URL : String
The API URL currently associated with this instance of UpcomingService.
UpcomingService
  _self : UpcomingService
UpcomingService
  token : String
The user token currently associated with this instance of UpcomingService.
UpcomingService
  _user : User
UpcomingService
  user : User
The user currently authenticated via this instance of UpcomingService.
UpcomingService
Public Methods
 MethodDefined by
  
UpcomingService(apikey:String)
UpcomingService constructor.
UpcomingService
  
addToWatchList(uevent:uEvent, status:String = null):void
This method adds a specified event to the user's watchlist, and assigns the user's status for this event (either "watch" or "attend").
UpcomingService
  
checkToken():Boolean
If the token is valid, this method will return true.
UpcomingService
  
findEvents(search_text:String = null, location:String = null, radius:Number, country:Country = null, state:State = null, metro:Metro = null, venue:Venue = null, category:Category = null, min_date:Date = null, max_date:Date = null, tags:Array = null, per_page:Number, page:Number, sort:String = null):void
This method allows you to search for events given a set of parameters.
UpcomingService
  
findMetros(search_text:String = null, country:Country = null, state:State = null):void
This method allows you to find a list of metros based on specific parameters.
UpcomingService
  
findVenues(search_text:String = null, location:String = null, radius:Number, country:Country = null, state:State = null, metro:Metro = null, per_page:Number, page:Number, sort:String = null):void
This method allows you to find venues where events take place, based on specific parameters.
UpcomingService
  
getCategoryList():void
This method requests a list of all available event categories.
UpcomingService
  
getCountryList():void
This method returns the list of all countries in the Upcoming.org database.
UpcomingService
  
getFrobURL():String
This method returns the authentication URL where the user can approve the application's access to his or her private data.
UpcomingService
  
getMetroByLatLon(latitude:Number, longitude:Number):void
This method returns one metro area closest to the specified latitude and longitude.
UpcomingService
  
getMetroListByState(state:State):void
This method returns all metro areas for a specific state.
UpcomingService
  
getMyMetroList():void
This method returns a list of all metro areas that the currently authenticated user is subscribed to.
UpcomingService
  
getMyWatchList(min_date:Date = null, max_date:Date = null, sort:String = null):void
This method retrieves a list of events currently watched by the authenticated user.
UpcomingService
  
getStateList(country:Country):void
This method returns the list of all states in a given country.
UpcomingService
  
getToken(frob:String):void
Using the frob received from the user or from Upcoming.org via a callback, this function retrieves and sets the token property.
UpcomingService
  
getVenueList(metro:Metro):void
This method requests a venue list for a particular metro area.
UpcomingService
  
removeFromWatchList(watchlist_id:Number):void
This method removes the user from a watchlist, given a watchlist id.
UpcomingService
Public Constants
 ConstantDefined by
  tokenEvent : String = "TokenEvent"
UpcomingService
Property detail
api_idproperty
api_id:String  [read-write]

The API key currently associated with this instance of UpcomingService.

Implementation
    public function get api_id():String
    public function set api_id(value:String):void
api_URLproperty 
api_URL:String  [read-write]

The API URL currently associated with this instance of UpcomingService. The default value is set to the current API entrypoint, but can be changed if necessary.

Implementation
    public function get api_URL():String
    public function set api_URL(value:String):void
_selfproperty 
public var _self:UpcomingService
tokenproperty 
token:String  [read-write]

The user token currently associated with this instance of UpcomingService.

Implementation
    public function get token():String
    public function set token(value:String):void

See also

getToken
_userproperty 
public var _user:User
userproperty 
user:User  [read-write]

The user currently authenticated via this instance of UpcomingService.

Implementation
    public function get user():User
    public function set user(value:User):void
Constructor detail
UpcomingService()constructor
public function UpcomingService(apikey:String)

UpcomingService constructor.

Parameters
apikey:String — The API key for your application. To register a new API key, follow the instructions provided here
Method detail
addToWatchList()method
public function addToWatchList(uevent:uEvent, status:String = null):void

This method adds a specified event to the user's watchlist, and assigns the user's status for this event (either "watch" or "attend"). The event must already exist in the Upcoming.org database. When the adding is complete, the current instance of UpcomingService dispatches a UpcomingResultEvent.WATCHLIST_ADDED event.

Parameters
uevent:uEvent — The event to add to the user's watchlist.
 
status:String (default = null) — The status of the user's attendance (Either "watch", or "attend").
checkToken()method 
public function checkToken():Boolean

If the token is valid, this method will return true. Otherwise, it'll return false

Returns
Boolean — A Boolean value indicating whether the token is valid.
findEvents()method 
public function findEvents(search_text:String = null, location:String = null, radius:Number, country:Country = null, state:State = null, metro:Metro = null, venue:Venue = null, category:Category = null, min_date:Date = null, max_date:Date = null, tags:Array = null, per_page:Number, page:Number, sort:String = null):void

This method allows you to search for events given a set of parameters. When the events are found, the current instance of UpcomingService dispatches a UpcomingResultEvent.EVENT_SEARCHevent. None of the parameters are required, and any combination of parameters can be included.

Parameters
search_text:String (default = null) — Keywords to look for in event names and descriptions
 
location:String (default = null) — The event location in the form similar to "City, State" or a comma-separated pair of latitude and longitude.
 
radius:Number — Radius, in miles, to search arond the specified location.
 
country:Country (default = null) — Country where the event takes place.
 
state:State (default = null) — State where the event takes place.
 
metro:Metro (default = null) — Metro area where the event takes place
 
venue:Venue (default = null) — A particular venue where the event takes place.
 
category:Category (default = null) — An event category, from a predefined Upcoming.org category list.
 
min_date:Date (default = null) — The minimum of the date range to search in.
 
max_date:Date (default = null) — The maximum of the date range to search in.
 
tags:Array (default = null) — Comma-separated event tags.
 
per_page:Number — Number of results returned per page.
 
page:Number — Number of the page of results.
 
sort:String (default = null) — Sorting order for the results. Can be one of the following: name-desc, name-asc, start-date-desc, start-date-asc, posted-date-asc, posted-date-desc, distance-asc, distance-desc.
findMetros()method 
public function findMetros(search_text:String = null, country:Country = null, state:State = null):void

This method allows you to find a list of metros based on specific parameters. Once the metros have been found, the current instance of UpcomingService dispatches an event UpcomingResultEvent.METRO_SEARCH.

Parameters
search_text:String (default = null) — Keywords to look for in the name or description of the metro.
 
country:Country (default = null) — Country where the metro area is located.
 
state:State (default = null) — State where the metro area is located.
findVenues()method 
public function findVenues(search_text:String = null, location:String = null, radius:Number, country:Country = null, state:State = null, metro:Metro = null, per_page:Number, page:Number, sort:String = null):void

This method allows you to find venues where events take place, based on specific parameters. When the list of events is found, the current instance of UpcomingService dispatches a UpcomingResultEvent.VENUE_SEARCHevent.

Parameters
search_text:String (default = null) — Keywords to look for in the venue name or description.
 
location:String (default = null) — Location of the venue, in the form similar to "City, state" or "zip".
 
radius:Number — Radius in miles in which to search around the location.
 
country:Country (default = null) — Country where the venue is located.
 
state:State (default = null) — State where the venue is located.
 
metro:Metro (default = null) — Metro area where the venue is located
 
per_page:Number — Number of results returned per page
 
page:Number — The page number of results
 
sort:String (default = null) — Sorting order for results, can be one of: name-desc, name-asc, distance-asc, distance-desc
getCategoryList()method 
public function getCategoryList():void

This method requests a list of all available event categories. The categories are pre-defined by Upcoming.org. When the list of categories is loaded, the current instance of UpcomingService dispatches a UpcomingResultEvent.CATEGORY_GET_LIST event.

getCountryList()method 
public function getCountryList():void

This method returns the list of all countries in the Upcoming.org database. When the results are ready, the current instance of UpcomingService dispatches UpcomingResultEvent.GET_COUNTRY_LIST event.

getFrobURL()method 
public function getFrobURL():String

This method returns the authentication URL where the user can approve the application's access to his or her private data. Once approved, the user will either be issued a frob to copy/paste back into your application, or, if you have supplied a callback URL, the user will be redirected to that URL with the frob passed as a parameter.

Returns
String — The authentication URL for your application.
getMetroByLatLon()method 
public function getMetroByLatLon(latitude:Number, longitude:Number):void

This method returns one metro area closest to the specified latitude and longitude. When the results are returns, the current instance of UpcomingService dispatches an UpcomingResultEvent.METRO_GET_LAT_LON event.

Parameters
latitude:Number — The latitude in proximity to a metro.
 
longitude:Number — The longitude in proximity to a metro.
getMetroListByState()method 
public function getMetroListByState(state:State):void

This method returns all metro areas for a specific state. The state is required to have the id field filled in. When the list is returns, the current instance of UpcomingService dispatches a UpcomingResultEvent.METRO_GET_LIST event.

Parameters
state:State — The state to get a list of metro areas for.
getMyMetroList()method 
public function getMyMetroList():void

This method returns a list of all metro areas that the currently authenticated user is subscribed to. A valid token is necessary to get the results. Once the results are returns, the current instance of UpcomingService dispatches a UpcomingResultEvent.METRO_GET_MY_LIST event.

getMyWatchList()method 
public function getMyWatchList(min_date:Date = null, max_date:Date = null, sort:String = null):void

This method retrieves a list of events currently watched by the authenticated user. The events are accompanied by watchlist ids and user's status ("watching" or "attending"). When the list is returned, the current instance of UpcomingService issues an UpcomingResultEvent.WATCHLIST_GET_LIST event.

Parameters
min_date:Date (default = null) — Minimum date for the list range.
 
max_date:Date (default = null) — Maximum date for the list range.
 
sort:String (default = null) — Sorting order for the results. Can be one of: 'start-date-asc', 'start-date-desc', 'post-date-asc', 'post-date-desc'
getStateList()method 
public function getStateList(country:Country):void

This method returns the list of all states in a given country. When the results are ready, the current instance of UpcomingService dispatches UpcomingResultEvent.GET_STATE_LIST event.

Parameters
country:Country — The country for which the list of states is retrieved.
getToken()method 
public function getToken(frob:String):void

Using the frob received from the user or from Upcoming.org via a callback, this function retrieves and sets the token property. When the token is received, this instance of UpcomingService dispatches an UpcomingResultEvent.GET_TOKEN event. If an error occurs, the event dispatched is instead a UpcomingErrorEvent.INVALID_FROB, or an UpcomingErrorEvent.XML_LOADING.

Parameters
frob:String — A code obtained by the user from the authentication URL or passed to the application via a URL callback.
getVenueList()method 
public function getVenueList(metro:Metro):void

This method requests a venue list for a particular metro area. When the list is returned, the current instance of UpcomingService dispatches a UpcomingResultEvent.VENUE_GET_LIST event.

Parameters
metro:Metro — The metro area to search for venues.
removeFromWatchList()method 
public function removeFromWatchList(watchlist_id:Number):void

This method removes the user from a watchlist, given a watchlist id. Once the removal is complete, the current instance of UpcomingService dispatches a UpcomingResultEvent.WATCHLIST_REMOVED event.

Parameters
watchlist_id:Number — The id of the watchlist to remove the user from.
Constant detail
tokenEventconstant
public const tokenEvent:String = "TokenEvent"



Visit ydn-flash for Yahoo! ASTRA feedback and support