NAME

Net::UPS - Implementation of UPS Online Tools API in Perl

SYNOPSIS

use Net::UPS;
$ups = Net::UPS->new($userid, $password, $accesskey);
$rate = $ups->rate($from_zip, $to_zip, $package);
printf("Shipping this package $from_zip => $to_zip will cost you \$.2f\n", $rate->total_charges);

WARNING

Although functional, this is an alpha software. Net::UPS is still under testing stage, and interface can change in the future without any notice. Until this warning sign is removed and Net::UPS version becomes at least 1.0, you are discouraged from using this software in production environment, or do not expect backward-compatible upgrades!

DESCRIPTION

Net::UPS implements UPS' Online Tools API in Perl. In a nutshell, Net::UPS knows how to retrieve rates and service information for shipping packages using UPS, as well as for validating U.S. addresses.

This manual is optimized to be used as a quick reference. If you're knew to Net::UPS, and this manual doesn't seem to help, you're encouraged to read Net::UPS::Tutorial first.

METHODS

Following are the list and description of methods available through Net::UPS. Provided examples may also use other Net::UPS::* libraries and their methods. For the details of those please read their respective manuals. (See SEE ALSO)

new($userid, $password, $accesskey)

new($userid, $password, $accesskey, \%args)

Constructor method. Builds and returns Net::UPS instance. If an instance exists, new() returns that instance.

$userid and $password are your login information to your UPS.com profile. $accesskey is something you have to request from UPS.com to be able to use UPS Online Tools API.

\%args, if present, are the global arguments you can pass to customize Net::UPS instance, and further calls to UPS.com. Available arguments are as follows

pickup_type: Type of pickup to be assumed by subsequent rate() and shop_for_rate() calls. See PICKUP TYPES for the list of available pickup types.
ups_account_number: If you have a UPS account number, place it here.
customer_classification: Your Customer Classification. For details refer to UPS Online Tools API manual. In general, you'll get the lowest quote if your pickup_type is DAILY and your customer_classification is WHOLESALE. See CUSTOMER CLASSIFICATION

instance()

Returns an instance of Net::UPS object. Should be called after an instance is created previously by calling new(). instance() croaks if there is no object instance.

userid()

password()

access_key()

Return UserID, Password and AccessKey values respectively

rate($from, $to, $package)

rate($from, $to, \@packages)

rate($from, $to, \@packages, \%args

Returns one Net::UPS::Rate instance for every package requested. If there is only one package, returns a single reference to Net::UPS::Rate. If there are more then one packages passed, returns an arrayref of Net::UPS::Rate objects.

$from and $to can be either plain postal (zip) codes, or instances of Net::UPS::Address. In latter case, the only value required is postal_code().

$package should be of Net::UPS::Package type and @packages should be an array of Net::UPS::Package objects.

$rate = $ups->rate(15146, 15241, $package);
printf("Your cost is \$.2f\n", $rate->total_charges);

See Net::UPS::Package for examples of building a package. See Net::UPS::Rate for examples of using $rate.

\%args, if present, can be used to customize rate()ing process. Available arguments are:

service: Specifies what kind of service to rate the package against. Default is GROUND, which rates the package for UPS Ground. See SERVICE TYPES for a list of available UPS services to choose from.

shop_for_rates($from, $to, $package)

shop_for_rates($from, $to, \@packages)

shop_for_rates($from, $to, \@packages, \%args)

The same as rate(), except on success, returns an array reference to a list of all the available services for the addresses and the package. Each service is represented as an instance of Net::UPS::Service. Example:

$services = $ups->shop_for_rates(15146, 15228, $package);
while (my $service = shift @$services ) {
    printf("%-22s => \$.2f", $service->label, $service->total_charges);
    if ( my $days = $service->guaranteed_days ) {
        printf("(delivers in %d day%s)\n", $days, ($days > 1) ? "s" : "");
    } else {
        print "\n";
    }
}

Above example returns all the service types available for shipping $package from 15146 to 15228. Output may be similar to this:

GROUND                 => $5.20
3_DAY_SELECT           => $6.35  (delivers in 3 days)
2ND_DAY_AIR            => $9.09  (delivers in 2 days)
2ND_DAY_AIR_AM         => $9.96  (delivers in 2 days)
NEXT_DAY_AIR_SAVER     => $15.33 (delivers in 1 day)
NEXT_DAY_AIR           => $17.79 (delivers in 1 day)
NEXT_DAY_AIR_EARLY_AM  => $49.00 (delivers in 1 day)

The above example won't change even if you passed multiple packages to be rated. Individual package rates can be accessed through rates() method of Net::UPS::Service.

service()

Returns the last service used by the most recent call to rate().

validate_address($address)

validate_address($address, \%args)

Validates a given address against UPS' U.S. Address Validation service. $address can be one of the following:

US Zip Code
Hash Reference: Keys of the hash should correspond to attributes of Net::UPS::Address
Net::UPS::Address class instance

%args, if present, contains arguments that effect validation results. As of this release the only supported argument is tolerance, which defines threshold for address matches. threshold is a floating point number between 0 and 1, inclusively. The higher the tolerance threshold, the more loose the address match is, thus more address suggestions are returned. Default tolerance value is 0.05, which only returns very close matches.

my $addresses = $ups->validate_address($address);
unless ( defined $addresses ) {
    die $ups->errstr;
}
unless ( @$addresses ) {
    die "Address is not correct, nor are there any suggestions\n";
}
if ( $addresses->[0]->is_match ) {
    print "Address Matches Exactly!\n";
} else {
    print "Your address didn't match exactly. Following are some valid suggestions\n";
    for (@$addresses ) {
        printf("%s, %s %s\n", $_->city, $_->state, $_->postal_code);
    }
}

AUTHOR

Sherzod B. Ruzmetov <sherzodr@cpan.org>, http://author.handalak.com/

COPYRIGHT

DISCLAIMER

THIS LIBRARY IS PROVIDED WITH USEFULNES IN MIND, BUT WITHOUT ANY GUARANTEE (NEITHER IMPLIED NOR EXPRESSED) OF ITS FITNES FOR A PARTICUALR PURPOSE. USE IT AT YOUR OWN RISK.

APPENDIXES

Some options need to be provided to UPS in the form of codes. These two-digit numbers are not ideal for mortals to work with. That's why Net::UPS decided to assign them symbolic names, constants, if you wish.

SERVICE TYPES

Following is the table of SERVICE TYPE codes, and their symbolic names assigned by Net::UPS. One of these options can be passed as service argument to rate(), as in:

$rates = $ups->rate($from, $to, $package, {service=>'2ND_DAY_AIR'});

+------------------------+-----------+
|    SYMBOLIC NAMES      | UPS CODES |
+------------------------+-----------+
| NEXT_DAY_AIR           |    01     |
| 2ND_DAY_AIR            |    02     |
| GROUND                 |    03     |
| WORLDWIDE_EXPRESS      |    07     |
| WORLDWIDE_EXPEDITED    |    08     |
| STANDARD               |    11     |
| 3_DAY_SELECT           |    12     |
| NEXT_DAY_AIR_SAVER     |    13     |
| NEXT_DAY_AIR_EARLY_AM  |    14     |
| WORLDWIDE_EXPRESS_PLUS |    54     |
| 2ND_DAY_AIR_AM'        |    59     |
+------------------------+-----------+

CUSTOMER CLASSIFICATION

Following are the possible customer classifications. Can be passed to new() as part of the argument list, as in:

$ups = Net::UPS->new($userid, $password, $accesskey, {customer_classification=>'WHOLESALE'});

+----------------+-----------+
| SYMBOLIC NAMES | UPS CODES |
+----------------+-----------+
| WHOLESALE      |     01    |
| OCCASIONAL     |     03    |
| RETAIL         |     04    |
+----------------+-----------+

PACKAGE CODES

Following are all valid packaging types that can be set through packaging_type attribute of Net::UPS::Package, as in:

$package = Net::UPS::Package->new(weight=>10, packaging_type=>'TUBE');

+-----------------+-----------+
| SYMBOLIC NAMES  | UPS CODES |
+-----------------+-----------+
| LETTER          |     01    |
| PACKAGE         |     02    |
| TUBE            |     03    |
| UPS_PAK         |     04    |
| UPS_EXPRESS_BOX |     21    |
| UPS_25KG_BOX    |     24    |
| UPS_10KG_BOX    |     25    |
+-----------------+-----------+

To install Net::UPS, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::UPS

CPAN shell

perl -MCPAN -e shell
install Net::UPS

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)