View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Brett T. Warden > WebService-Sprint-0.02 > WebService::Sprint



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.02   Source   Latest Release: WebService-Sprint-0.50


WebService::Sprint - an interface to Sprint's web services


Version 0.02


Provides an object-oriented interface to Sprint's developer web services, including geolocation of Sprint devices.

Disclaimer: I am not affiliated with Sprint. This is an implementation of their publicly-available specifications. Sprint is probably a registered trademark, and is used here to highlight that this implementation is specific to the Sprint network.

Implements some features of Sprint's developer web services. For more information, see:

Currently supports:

Does not support:

                use WebService::Sprint;

                my $ws = WebService::Sprint->new(
                        key      => '0123456789abcdef',
                        secret => 'fedcba98765432100123456789abcdef',

                # Get the list of devices associated with your developer account
                my $devices = $ws->get_devices(

                  # Optionally limit to devices in a particular state
                        type   => 'approved',

                # Fetch the network location of a single device
                my $location = $ws->get_location(
                        mdn    => '2225551212',

                # Fetch the location of multiple devices (issues multiple queries behind the scenes, serially)
                my @locations = $ws->get_location(
                        mdn    => [qw(2225551212 8885551234)],

                # Check whether a device is within a given geofence
                my $presence = $ws->check_presence(
                        mdn       => '2225551212',

                        # Geofence coordinates in Decimal Degrees
                        latitude  => 45.000,
                        longitude => -120.000,

                        # Radius in meters (server expects at least 2000 meters)
                        radius    => 5000,



Instantiates a Web Service object. Named arguments include: key: Your Sprint-assigned developer key secret: Your Sprint-assigned shared secret base_url: The base URL for Sprint services (defaults to user_agent: HTTP user agent used (defaults to WebService::Sprint)


Given no arguments, returns a hashref of devices associated with your developer account, indicating status. Given the argument mdn with a valid 10-digit phone number, returns information about that device only. Given the argument type (pending, declined, deleted, approved, all), returns information about only that subset of devices associated with your account.


Given the argument mdn as a single or list of 10-digit phone numbers, returns a hashref (or list of hashrefs) with detailed information about the presence of the requested device on the Sprint network.

This call should not use your credits.


Given the argument mdn as a single or list of 10-digit phone numbers, returns a hashref (or list of hashrefs) with detailed information about the network-based location of the requested device.

WARNING: This uses credits (3 per device query, last I checked)!


Works similarly to get_location, but is intended to determine whether a given device is within a specified geofence. Takes the additional (required) parameters latitude, longitude (both in decimal degrees), and range (in meters). Returns location information, the specified geofence, and whether the device is inside the defined fence.

This is a distincly different service call to Sprint, even though it could be implemented with some geo-math around get_location. Specifically, this service call attempts to obtain a higher-precision location, and consequently, Sprint charges more credits for its use.

WARNING: This uses credits (6 per device query, last I checked)!


These are underlying methods that may be useful to extend this module for use with additional services.


Given a list of named arguments, issues a web service request. Calling this method takes care of timestamp and authentication/hashing requirements for you. Provided for your convenience to access unimplemented services.


Given a list of named arguments, constructs the service URL, adding the timestamp and hash. Called by issue_query, and provided for your convenience.


Given a named argument url, retrieves the URL. If successful, returns the content. If failed, returns the status message. Called by issue_query, and provided for your convenience.


Given a named argument json containing the JSON response from a web service query, attempts to decode the JSON into a hash ref. Attempts to remove the extraneous line feeds that appear in some responses.


Given a named argument list, orders the keys and calculates the authentication hash, based on the shared secret. This method is called internally when building a request URI, but is provided for your convenience.


Returns the object's stored key. Provided for your convenience


Retuns the object's stored shared secret. Provided for your convenience.


Brett T. Warden, <bwarden at>


Please report any bugs or feature requests to bug-webservice-sprint at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


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

    perldoc WebService::Sprint

You can also look for information at:



Copyright 2011 Brett T. Warden.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.

syntax highlighting: