NAME

USPS::RateRequest - Ultra fast parallelized asyncronous USPS rate lookups.

VERSION

version 1.0004

SYNOPSIS

 use USPS::RateRequest;
 use Box::Calc;
 use Ouch;

 my $calc = Box::Calc->new();
 $calc->add_box_type(...);
 $calc->add_item(...);
 $calc->pack_items;

 my $rates = eval {
    USPS::RateRequest->new(
        user_id     => 'usps username'
        password    => 'usps password',
        from        => 53716,
        postal_code => 90210,
        country     => 'US',
     )->request_rates($calc->boxes)->recv;
 };

 if (hug) {
    die "USPS Error: $@";
 }

 my $priority_postage_for_first_box = $rates->{$calc->get_box(0)->id}{'USPS Priority'}{postage};

 # view the complete data structure
 use Data::Dumper;
 say Dumper($rates);

DESCRIPTION

USPS::RateRequest exists for two reasons:

• Business::Shipping is very slow when you have to request rates for varying amounts and sizes of parcels. That's because each request is done in serial. USPS::RateRequest makes all requests in parallel, thus increasing performance dramatically.

• Box::Calc does a ton of work figuring out exactly what can be packed into each parcel. USPS::RateRequest takes advantage of all that data being loaded and makes use of it to calculate very precise package dimensions and weights to get the most accurate shipping prices.

If there are errors returned from the USPS, USPS::RateRequest will throw exceptions via Ouch with the code "USPS Error" and the error returned from the USPS. If no rates are returned at all, then it will throw an exception with the code "No Rates".

METHODS

new( params )

Constructor.

params

A hash of initialization parameters. An asterisk denotes required parameters.

test_mode

Boolean. If true requests will be posted to the USPS test server rather than the production server.

prod_uri

The URI to the production instance of the USPS web tools web services. Defaults to http://production.shippingapis.com/ShippingAPI.dll.

test_uri

The URI to the test instance of the USPS web tools web services. Defaults to http://testing.shippingapis.com/ShippingAPItest.dll.

user_id (*)

The username provided to you by signing up for USPS web tools here: https://www.usps.com/business/web-tools-apis/welcome.htm

password (*)

The password that goes with user_id.

from (*)

The zip code from which the parcels will ship.

postal_code (*)

The postal_code code where the parcels will be delivered.

country (*)

The name of the country where the parcels will be delivered. See the USPS web services documentation for a list of valid countries. https://www.usps.com/business/web-tools-apis/price-calculators.htm The proper name for the USA is "United States of America".

service

Defaults to all. Optionally limit the response to specific delivery services, such as PRIORITY. See the USPS web service documentation for details: https://www.usps.com/business/web-tools-apis/price-calculators.htm

debug

Add additional items into the returned rate request data for debugging issues with rate lookups and name sanitization. This data is not guaranteed to stay the same from release to release.

request_rates ( boxes )

Returns an AnyEvent condition variable. When you call the recv method on that variable it will send out all the requests for rates, collate and translate the responses, and return a hash reference that looks like this:

 {
        'box-id-1' => {
                        'USPS Priority Small Flat Rate Box' => {
                                                               'postage' => '5.80'
                                                             },
                        'USPS Priority Express Hold For Pickup' => {
                                                                   'postage' => '56.05'
                                                                 },
                        'USPS Priority Express Flat Rate Envelope' => {
                                                                      'postage' => '19.99'
                                                                    },
                        'USPS Priority Medium Flat Rate Box' => {
                                                                'postage' => '12.35'
                                                              },
                        'USPS Standard Post' => {
                                                'postage' => '13.34'
                                              },
                        'USPS Media' => {
                                        'postage' => '4.61'
                                      },
                        [....]
        },
        'box-id-2' => {
                        [....]
        },
        [....]

 }

boxes

An array reference of boxes created by Box::Calc.

sanitize_service_name ( name )

domestic ( )

Returns a 1 or 0 depending upon whether the country is 'United States of America'.

CAVEATS

Although Box::Calc doesn't care what units you use for weights and measurements, USPS does. Make sure all your weights are in ounces and all your measurements are in inches.

AUTHOR

JT Smith <jt_at_plainblack_dot_com>

LEGAL

Box::Calc is Copyright 2014 Plain Black Corporation (http://www.plainblack.com) and is licensed under the same terms as Perl itself.