WebService::Sprint - an interface to Sprint's web services
Provides an object-oriented interface to Sprint's developer web services, including geolocation of devices on Sprint's CDMA network in the United States.
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:
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', ); # Request addition of a device to your account (requires user approval # via SMS) my $device = $ws->add_device( mdn => '2225551212', ); # Remove a device from your account my $device = $ws->del_device( mdn => '2225551212', ); # Check whether a given device is present on the network my $presence = $ws->get_presence( mdn => '2225551212', ); # 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 $location = $ws->check_perimeter( mdn => '2225551212', # Geofence coordinates in Decimal Degrees latitude => 45.000, longitude => -120.000, # Radius in meters (server requires 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 http://sprintdevelopersandbox.com/developerSandbox/resources/v1/) 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 with a valid 10-digit phone number, attempts to add the user to your account. Returns a hashref including status of the request.
Given the argument mdn with a valid 10-digit phone number, attempts to remove the user from your account. Returns a hashref including status of the request.
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 location of the requested device. This usually returns a network-determined low-precision location for the device, and completes within about 5 seconds. It usually does not activate the device's GPS receiver.
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 radius (in meters). Returns location information, the specified geofence, and whether the device is inside the defined fence.
This is a distinctly 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. Usually it will trigger a GPS location request on the device itself, and may take around 40 seconds to complete.
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 herein-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.
Returns the object's stored shared secret. Provided for your convenience.
Brett T. Warden,
<bwarden at cpan.org>
Please report any bugs or feature requests to
bug-webservice-sprint at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Sprint. 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.
You can also look for information at:
Copyright 2011-2012 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 http://dev.perl.org/licenses/ for more information.