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


version 1.0004


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

 my $calc = Box::Calc->new();

 my $rates = eval {
        user_id     => 'usps username'
        password    => 'usps password',
        from        => 53716,
        postal_code => 90210,
        country     => 'US',

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


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".


new( params )



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


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


The URI to the production instance of the USPS web tools web services. Defaults to


The URI to the test instance of the USPS web tools web services. Defaults to

user_id (*)

The username provided to you by signing up for USPS web tools here:

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. The proper name for the USA is "United States of America".


Defaults to all. Optionally limit the response to specific delivery services, such as PRIORITY. See the USPS web service documentation for details:


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' => {


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'.


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.


JT Smith <jt_at_plainblack_dot_com>


Box::Calc is Copyright 2014 Plain Black Corporation ( and is licensed under the same terms as Perl itself.