/ 
WebService-Sprint-0.02
River stage zero No dependents
/ WebService::Sprint

NAME

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

VERSION

Version 0.02

SYNOPSIS

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:

  • presence

  • location (3G)

  • geofence perimeter check

  • User management -- retrieving list of devices

Does not support:

  • All other geofence operations

  • SMS

  • User management -- adding or removing devices

  • iDen Content Uploader

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,
);

METHODS

new

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)

get_devices

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.

get_presence

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.

get_location

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)!

check_perimeter

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)!

EXTRA METHODS

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

issue_query

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.

build_url

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

fetch_url

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.

decode_response

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.

get_hash

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.

get_key

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

get_secret

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

AUTHOR

Brett T. Warden, <bwarden at cpan.org>

BUGS

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.

SUPPORT

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

perldoc WebService::Sprint

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

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 http://dev.perl.org/licenses/ for more information.