NAME

WebService::Upcoming - Perl interface to the Upcoming API

SYNOPSIS

  use WebService::Upcoming;

  my $upco = new WebService::Upcoming("*** UPCOMING API KEY HERE ***");
  my $objc = $upco->call("event.search",
              {
                  "search_text" => "music"
              });
  die("ERROR: ".$upco->err_text()."\n") if (!defined($objc));
  foreach (@{$objc})
  {
        print("EVENT: ".$_->name()." on ".$_->start_date()."\n");
  }

DESCRIPTION

A simple interface for using the Upcoming API.

WebService::Upcoming is a subclass of LWP::UserAgent, so all of the various proxy, request limits, caching, and other features are available.

METHODS

new($key [, $version ])

Creates an WebService::Upcoming object. $key is the API key used to identify the client to the Upcoming server. $version is the version of the Upcoming API to call, and it defaults to "1.0" if excluded.

API keys may be obtained from http://upcoming.org/services/api/keygen.php.

key( [ $key ] )

Sets or retrieves the current API key.

call($method, \%args)

Constructs and executes a request to upcoming.org, returning an array of objects that define the response.

$method defines the Upcoming API method to call. \%args is a reference to a hash containing arguments to the method.

Each call() returns a reference to an array of WebService::Upcoming::Object::* objects, depending on the request. event.getInfo, for instance, will return WebService::Upcoming::Object::Event objects, with methods for each attribute: id(), name(), description(), etc. Empty arrays can also be returned, indicating a successful call(), but without any response, such as watchlist.remove.

On failure, call() returns undef. HTTP error codes are available through $upco->err_code(), human-readable error text is available through $upco->err_text().

Version 1.0 of the Upcoming API includes the following objects, all represented in the Perl namespace WebService::Upcoming::Object: Category, Country, Event, Metro, State, User, Venue and Watchlist.

For a list of methods, their arguments and what object to expect in response, see http://www.upcoming.org/services/api/. For each XML response in the Upcoming documentation, the attributes are available through methods of the same name on the WebService::Upcoming::Object::* objects.

query($method, \$args)

Constructs and executes a request to upcoming.org, returning the XML response.

$method defines the Upcoming API method to call. \%args is a reference to a hash containing arguments to the method.

See <call()> for details.

parse($method, $response)

Parses an API response from upcoming.org, returning an array of objects that define the response.

$method defines the Upcoming API method that generated the response. $response is the XML sent by the server.

See <call()> for details.

err_code()

Returns the last HTTP error code. Only valid if call() returns undef.

err_text()

Returns the last human-readable error text. Only valid if call() returns undef.

AUTHOR

Copyright (C) 2005, Greg Knauss, <greg@eod.com>

SEE ALSO

http://www.upcoming.org/, http://www.upcoming.org/services/api/