The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

WebService::BorisBikes - A very simple web service to wrap around the live Barclays cycle hire availibility data from the Transport for London website.

To use this module, please register and create an account at transport for london first. http://www.tfl.gov.uk/businessandpartners/syndication/default.aspx

and always follow the usage guidelines .. http://www.tfl.gov.uk/tfl/businessandpartners/syndication/assets/syndication-developer-guidelines.pdf

VERSION

version 0.14

SYNOPSIS

    use WebService::BorisBikes;

    my %params = ( 
        refresh_rate    => 120,    ## seconds
        debug_filename  => '/tmp/tflcycledata.xml',   
    );
    
    my $BB = WebService::BorisBikes->new( \%params );

PUBLIC METHODS

new

Returns a WebService::BorisBikes object. Accepts a hashref with possible keys of refresh_rate & debug_filename.

The refresh rate specifies in seconds how often to update station information. Refresh is performed automatically if needed after calling one of the public methods.

The debug_filename specifies the absolute position of a local London Cycle Scheme XML feed and is used for testing and debugging.

get_station_by_id

Returns a WebService::BorisBikes::Station object of the given id

    my $Station = $BB->get_station_by_id(533);

get_all_stations

Returns an hashref with keys being the station_id and values being a WebService::BorisBikes::Station object.

    my $rh_stations = $BB->get_all_stations();

get_meters_distance_between_two_stations

Returns the distance in meters between two station id's.

    my $meters = $BB->get_meters_distance_between_two_stations(566,547);
 

get_stations_nearby

Accepts a hashref, where the keys must contain 'distance' in meters and one of the following ..

  1. latlong => A comma delimited string of a valid latitude and longitude

        my $rhh_stations = $BB->get_stations_nearby( 
            { 'distance' => 200, latlong => '52.521,-0.102' }
        );
  2. postcode => A valid UK postcode (in greater London).

        my $rhh_stations = $BB->get_stations_nearby( 
            { 'distance' => 200, postcode => 'EC1M 5RF' }
        );

If you do populate both latlong and postcode params, the latlong will be used, and the postcode ignored.

Returns a hashref with the keys being station_ids and values being ...

    'distance' => in meters from the postcode/latlong argument 
    'obj' => the WebService::BorisBikes::Station object.  

For example:

   '246' => {
               'obj' => bless( {
                   'id'           => '246'
                   'nbEmptyDocks' => '39',
                    ...
               }, 'WebService::BorisBikes::Station' ),
               'distance' => '248.45237388466'

get_station_ids_nearby_order_by_distance_from

Accepts the same parameters as get_stations_nearby, but returns an arrayref of station ids, ordered by distance from.

my $ra_stations = $BB->get_station_ids_nearby_order_by_distance_from ({ postcode => 'EC1M 5RF', });

get_stations_by_name

Search for station by their name attribute with case insensitive matching. Returns a hashref, keys being station id and values being WebService::BorisBikes::Station object.

    my $rh_stations = $BB->get_stations_by_name('holland park');

PRIVATE METHODS

_get_stations_near_lat_long

Accepts latitude, longitude and distance parameters finds the stations within range.

_refresh_stations

Populates $self->{stations} hashref. The key being the station_id, and the value is a WebService::BorisBikes:Station object.

   $self->{stations}->{1} = WebService::BorisBikes::Station

_needs_refreshing

Returns true if our station data has become stale. Returns false otherwise.

_get_station_data

If $self->{debug_filename} is not set, station data will be retrieved from the tfl website using LWP::Simple.

Otherwise, station data will be slurped from a downloaded xml file in the absolute location of $self->{debug_filename}.

Returns an hashref of station data hashes, after setting $self->{epoch_since_last_refresh}.

_coordinates_in_greater_london

Return true if coordinate arguments are within a bounding box roughly the size of greater London.

_get_meters_distance_between_station_and_coordinates

Returns the distance in meters between a WebService::BorisBikes::Station object and WGS84 coordinates.

_get_meters_distance_between_two_coordinates

Uses GIS::Distance::Lite to calculate the distance in meters between two WGS84 coordinates, (Haversine formula).

_get_coordinates_from_place

Accepts the same hashref as WebService::BorisBikes::get_stations_nearby() and returns a latitude and longitude.

_validate_lat_long

Returns true if parameters latitude is a float between -180 and 180 and longitude is a float between -90 and 90.