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

NAME

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

VERSION

Version 0.50

DESCRIPTION

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:

Currently supports:

  • Presence

  • Location (3G)

  • Geofence perimeter check

  • User management -- retrieving list of devices, adding or removing devices

Does not support:

  • All other geofence operations

  • SMS

  • iDen Content Uploader

SYNOPSIS

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

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.

add_device

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.

del_device

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.

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

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

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 herein-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

Returns 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:

ACKNOWLEDGMENTS

LICENSE AND COPYRIGHT

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.