NAME
       WWW::PIDS - Perl API for the tramTRACKER PIDS Web Service

SYNOPSIS
       WWW::PIDS is a Perl API to the PIDS tramTRACKER web service.

       The tramTRACKER PIDS web service "is a public Web Service that provides a set of Web Methods to request real-time and scheduled
       tram arrival times, as well as stops and routes information."

       You can find more infomration on the tramTRACKER PIDS web service here <http://ws.tramtracker.com.au/pidsservice/pids.asmx>.

       This Perl API aims to implement a one-to-one binding with the methods provided by the web service.  Accordingly, the method
       names within this package are named after the corresponding names of the methods exposed via the web service.  Unfortunately,
       this results in some exceedingly long camel-cased method names - those wanting more aesthetically named methods and slightly
       more usable syntax may prefer the WWW::PIDS::Sugar package.

           use WWW::PIDS;

           my $p = WWW::PIDS->new();

           ...

METHODS
   new ( %ARGS )
       Constructor - creates a new WWW::PIDS object.

       This method accepts four optional parameters, if any parameter is ommitted a default value will be used.  The parameters and
       their defaults are:

       ·   ClientGuid

           The client GUID that must be passed to the tramTRACKER PIDS web service.  If you do not pass this parameter, then on
           instatiation of a new WWW::PIDS object an implicit call will be made to the GetNewClientGuid() method requesting a new GUID.

       ·   ClientType

           A string identifying the client application type.  If you require a dedicated client type, contact
           feedback@yarratrams.com.au.

           The default value for this parameter is 'WEBPID'.

       ·   ClientVersion

           The version of the client application.  The version must match the regex:

                   ^(\d{1,3}\.)(\d{1,3}\.)(\d{1,3}\.)(\d{1,5})$

           The default value for this parameter is the module version.

       ·   ClientWebServiceVersion

           The current Web Service version that the client application is connecting to.  The version format has to match the following
           expression:

                   ^(\d{1,3}\.)(\d{1,3}\.)(\d{1,3}\.)(\d{1,5})$

           The default value for this parameter is the current web service version (6.4.0.0).

   GetNewClientGuid ()
       Returns a new client GUID for use with the tramTRACKER PIDS web service.

   GetDestinationsForAllRoutes ()
       Returns a list of destinations for all routes in the network.

       The return type is an array of WWW::PIDS::Destination objects.

   GetDestinationsForRoute ( routeNo => SCALAR )
       Accepts a single mandatory parameter; the route number - and returns a WWW::PIDS::RouteDestination object containing route
       destination information for the specified route.

   GetListOfStopsByRouteNoAndDirection ( routeNo => SCALAR, isUpDirection => BOOLEAN )
       Accepts two mandatory parameters; the route number, and an boolean value (either 0 or 1) indicating if the direction of travel
       is in the "up" direction according to the service specification.

       Returns an array of WWW::PIDS::ListedStop objects representing an in-order list of the stops on the route in the direction of
       travel.

       Please see the NOTES section regarding the terminology, convention, and specifities of this module including naming of
       parameters.

   GetMainRoutes ()
       Returns an array of WWW::PIDS::RouteNo objects containing information on all main routes.

   GetMainRoutesForStop ( stopNo => SCALAR )
       Accepts a single mandatory parameter; the stop number for which you wish to retrieve a list of main routes, and returns an array
       of WWW::PIDS::RouteNo obejcts representing the main routes for the specified stop.

   GetNextPredictedArrivalTimeAtStopsForTramNo ( tramNo => $tramNo )
       Accepts a single mandatory parameter; the tram number for which you wish to retrieve the predicted stop arrival time, and
       returns a WWW::PIDS::PredictedArrivalTimeData object.

   GetNextPredictedRoutesCollection ( stopNo => $stopNo, routeNo => $routeNo, lowFloor => $lowFloor )
       Returns real-time predicted arrival times for the specified stop number, route number, and low floor requirement.

       This method accepts three mandatory parameters;

       ·   stopNo

           The stop number for which you would like to retrieve predicted arrival times.

       ·   routeNo

           The route number for which you would like to retrieve predicted arrival times.

       ·   lowFloor

           A boolean value (either 1 or 0) which if set to true will return data for low floor services only.

       This method returns an array of WWW::PIDS::ScheduledTime objects.

   GetPlatformStopsByRouteAndDirection ( routeNo => $routeNo, isUpDirection => BOOLEAN )
       Accepts two mandatory parameters; the route number and a boolean indicating the direction of the service.

       This method, although present in the PIDS web service documentation, does not appear to be implemented and hence results in a
       server-side error when invoked.

       It is included in this module for consistency and parity.

   GetRouteStopsByRoute ( routeNo => $routeNo, isUpDirection => $isUpDirection )
       Returns route stop information for the specified route in the specified direction.

       This method accepts two mandatory parameters:

       ·   routeNo

           The route number for which stop information should be returned.

       ·   isUpDirection

           A boolean value (either 1 or 0) indicating if the route stop information should be returned for the "up" direction of the
           route.

           This method returns an array of WWW::PIDS::RouteStop objects.

   GetRouteSummaries ()
       Returns a list of summaries for all main routes in the network.

       At the time of authoring, the PIDS web service currently returns an empty response for this method, hence this method, whilst
       being implemented internally, also returns nothing.

       It is included in this module for consistency and parity.

   GetSchedulesCollection ( stopNo => $stopNo, routeNo => $routeNo, lowFloor => BOOLEAN, clientRequestDateTime => TIMESTAMP )
       This method accepts four mandatory parameters and returns an array of three WWW::PIDS::PredictedTime objects representing the
       next three scheduled passing times for services with the specified stop number, route number, low floor requirement, day, and
       time.

       The four mandatory parameters are:

       ·   stopNo

           The stop number for which you would like to retrieve scheduled arrival times.

       ·   routeNo

           The route number for which you would like to retrieve scheduled arrival times.

       ·   lowFloor

           A boolean value (either 1 or 0) which if set to true will return data for low floor services only.

       ·   clientRequestDateTime

           The date and time representing the start of the period for which you would like to retrieve scheduled arrival times in the
           format:

                   YYYY-MM-DDThh:mm:ss

                   # Example
                   2015-05-08T16:20:00

   GetSchedulesForTrip ( tripID => $tripID, scheduledDateTime => TIMESTAMP )
       This method accepts two mandatory parameters and returns an array of WWW::PIDS::TripSchedule objects representing the scheduled
       arrival times pertaining to a route for the specified trip ID and scheduled departure date and time.

       To determine the trip ID, use the GetSchedulesCollection() method.

       The two mandatory parameters are:

       ·   tripID

           The trip ID identifying the route for which scheduled arrival times are to be retrieved.

       ·   scheduledDateTime

           The date and time representing the start of the period for which you would like to retrieve scheduled arrival times in the
           format:

                   YYYY-MM-DDThh:mm:ss

                   # Example
                   2015-05-08T16:20:00

   GetStopInformation ( stopNo => $stopNo )
       Returns a WWW::PIDS::StopInformation object containing information on the specified stop ID.  The WWW::PIDS::StopInformation
       object contains information including the flag stop number, latitude and logitude coordinates, and the suburb name.

       This method accepts a single mandatory parameter:

       stopNo
           The 4-digit tracker ID of the stop for which infomration is to be retrieved.

   GetStopsAndRoutesUpdatesSince( dateSince => TIMESTAMP )
       Returns a WWW::PIDS::CoreDataChanges object containing a list of routes and tracker IDs whose information have been updated
       since the date specified in the parameter (dateSince). To obtain detailed information of the updates, use the
       GetStopInformation(), GetListOfStopsByRouteNoAndDirection(), and GetDestinationsForRoute() methods.

       ·   dateSince

           The date and time representing the start of the period for which you would like to retrieve scheduled arrival times in the
           format:

                   YYYY-MM-DDThh:mm:ss

                   # Example
                   2015-05-08T16:20:00

NOTES
       Many of the methods, parameters, attributes, stylistic and design choices in this module may appear to be (at first glance)
       nonsensical, unintuitive, and ill-informed.

       However, the key philosophy in implementing this module has been to maintain strict adherence to the conventions and naming used
       in the official tramTRACKER PIDS web service, and as such, where at all possible, the naming conventions used there have been
       maintained herein.

       This has been done intentionally to try to maintain consistency between the web service and this module so as to try and reduce
       any potential source of confusion for users when attempting to mentally map the methods of one to the other, and also to try and
       provide a very close mapping of the official API to this binding.

       Likewise, the extensive use of objects as a return type for even very simple methods has been done for the purposes of
       consistency and with the philosophy that an object provides some level of mapping to the official SOAP response type.

       If you would prefer more aesthetically named methods and slightly more usable syntax, then please consider the WWW::PIDS::Sugar
       package.

AUTHOR
       Luke Poskitt, "<ltp at cpan.org>"

BUGS
       Please report any bugs or feature requests to "bug-www-pids at rt.cpan.org", or through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-PIDS>.  I will be notified, and then you'll automatically be notified of
       progress on your bug as I make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

           perldoc WWW::PIDS

       You can also look for information at:

       ·   tramTRACKER PIDS Web Service

           <http://ws.tramtracker.com.au/pidsservice/pids.asmx>

       ·   RT: CPAN's request tracker (report bugs here)

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-PIDS>

       ·   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/WWW-PIDS>

       ·   CPAN Ratings

           <http://cpanratings.perl.org/d/WWW-PIDS>

       ·   Search CPAN

           <http://search.cpan.org/dist/WWW-PIDS/>

SEE ALSO
       WWW::PIDS::CoreDataChanges WWW::PIDS::Destination WWW::PIDS::ListedStop WWW::PIDS::NextPredictedStopDetail
       WWW::PIDS::PredictedTime WWW::PIDS::PredictedArrivalTimeData WWW::PIDS::RouteChange WWW::PIDS::RouteDestination
       WWW::PIDS::RouteNo WWW::PIDS::ScheduledTime WWW::PIDS::StopChange WWW::PIDS::StopInformation WWW::PIDS::TripSchedule

LICENSE AND COPYRIGHT
       Copyright 2015 Luke Poskitt.

       This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You
       may obtain a copy of the full license at:

       <http://www.perlfoundation.org/artistic_license_2_0>

       Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using,
       modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not
       accept this license.

       If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required
       to ensure that your Modified Version complies with the requirements of this license.

       This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

       This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell,
       import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are
       necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any
       party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall
       terminate on the date that such litigation is filed.

       Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR
       IMPLIED WARRANTIES.  THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE
       DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE
       FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED
       OF THE POSSIBILITY OF SUCH DAMAGE.

