/ 
WWW-PIDS-0.01
River stage zero No dependents
/ WWW::PIDS

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:

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.