This library is meant to interface with the web services of USPS. It grew out of early dabbling of the USPS_Tracker plugin. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby API. Awesome USPS started as an extension of Active Shipping but at the moment I am still struggling with how best to accomplish integration. While working on the problem I decided to release my current work as a separate plugin for all to enjoy.

The original plugin has now been converted to a gem by [Wes Morgan from TurboVote.org]:http://turbovote.org/.

• 1.0.1 - replace hpricot with nokogiri because hpricot is no longer maintained
• 1.0.0 - initial gem release

• nokogiri for parsing the XML
• mocha for the tests

gem install awesome-usps

Add this to your Gemfile:

gem 'awesome-usps'

USPS can be a bit frustrating when starting working with them. First you must apply for a [USPS web tools account]:https://secure.shippingapis.com/registration/

This will net you a USPS user name assigned by them and a password. The password is for older versions of their api so you do not need to concern yourself with it.

Secondly you only have access to the Testing Server. You should run one of the canned response to make sure everything is setup up correctly.

usps.canned_tracking

You should receive an array as a response.

From there you need to email USPS for your account to be changed over to production so you can send live data. This does not hold true for all their API some of which require and additional level of clearance. See Below.

USPS is kinda... bad with how they handle their various label creation APIs. Except for their Priority Mail® Open and Distribute API you must make an additional email or call to their customer care center to have your permission turned on to send live data to the server. It is even more complicated if you wish to create your own labels with your company logo from their response xml. See their API documentation located at [http://www.http://www.usps.com/webtools/htm/Delivery-Confirmation.htm]:http://www.usps.com/webtools/htm/Delivery-Confirmation.htm for details on the procedure.

These APIs; Specifically Address Verify, Zip Lookup, and City State Lookup also need separate permission for use of live data.

Because most of the API's require an additional level of permission to use with live data every method has a canned test. They are both useful for integrating the returned data with your system and for testing that the library has not been compromised. A canned method follow this format. canned_method_name_test.

API methods are as follow

• track
• veryify_address
• zip_lookup
• city_state_lookup
• delivery_confirmation_label
• signature_confirmation_label
• merch_return
• express_mail
• express_mail_international_label
• priority_mail_international_label
• first_class_international_label
• open_distrubute_priority_label
• priority_mail_estimated_time
• standard_mail_estimated_time
• domestic_rates
• world_rates

Object Methods are as follow

• Package.new
• Location.new
• International Location #Only used in conjunction with international labels API

#In your environment.rb or production.rb include FotoVerite

usps = USPS.new('Your user name')

# Package up a poster and a Wii for your nephew.

packages = [
  Package.new(  100,                        # 100 grams
                [93,10],                    # 93 cm long, 10 cm diameter
                :cylinder => true),         # cylinders have different volume calculations

  Package.new(  (7.5 * 16),                 # 7.5 lbs, times 16 oz/lb.
                [15, 10, 4.5],              # 15x10x4.5 inches
                :units => :imperial)        # not grams, not centimetres
]

#Create a location to use with the Api sender =Location.new(:name => "Matthew Bergman ",:first_name => "Matthew", :last_name => "Bergman", :address1 => Apt 4m, :address2 => "1001 Pine Street", :city => "New York", :state => "NY", :zip5 => "100010", :phone => "5555555555")

#International Item Class #Only should be used in conjunction with the Internal Label Api Items = [ InternationalItem.new( :description => Pens", :quantity => "50" :value => 200.40, #Will be converted back to a float if entered as a string. :ounces => "50", :tariff_number => "Only use if known" #Optional input for the api. :country => "United States")

InternationalItem.new(
:description => "Against The Day, Pynchon",
  :quantity => "10"
  :value => 100.25
  :ounces => "250"
  :country => "United States")

]

#The api is very quirky about how it handles addresses. :address1 is for
inputing Apt or Suite numbers and nothing else.
#Besides the obvious info, it can contain, :facility_type and
:from_urbanization, which are used for specific Apis.

##To track a package

USPS.track("Tracking Number")

#This will return an array of tracking events example shown below

[{:eventzipcode=>"33436", :event=>"Arrival at Unit", :eventtime=>"7:23 am", :eventdate=>"June 14, 2008", :eventcity=>"BOYNTON BEACH", :eventstate=>"FL"}, {:eventzipcode=>"32862", :event=>"Processed", :eventtime=>"9:50 pm", :eventdate=>"June 13, 2008", :eventcity=>"ORLANDO", :eventstate=>"FL"}, {:eventzipcode=>"07032", :event=>"Processed", :eventtime=>"1:19 am", :eventdate=>"June 13, 2008", :eventcity=>"KEARNY", :eventstate=>"NJ"}, {:eventzipcode=>"07024", :event=>"Acceptance", :eventtime=>"3:03 pm", :eventdate=>"June 12, 2008", :eventcity=>"FORT LEE", :eventstate=>"NJ"}]

#Loop through and display as you wish

##To get rates for a single or group of packages.

#There are two APIs. One for domestic, the other for international packages.

USPS.domestic_rates(ZIP, Packages, options={}) USPS.world_rates(Country, Packages, options={})

#Both will return and array containg a hash of rates for each package.

#To access a rate hash for use you can do

array = USPS.world_rates(Country, Packages, options={}) array[0][Priority Mail International]

#You can also loop through and sort

##Address Verification

#All methods here will take a location array of up to five address

#To verify an address and fill in missing information. If mulitple addresses were found for an address :verified => false usps.veryify_address("locations array")

#Will fill in missing zip5 and zip4 for an address usps.zipcode_lookup("location array")

#Will fill in missing City and State for an address usps.city_state_lookup

##Service Standards

usps.priority_mail_estimated_time(origin, destination) usps.standard_mail_estimated_time(origin, destination)

#Both of these methods returns a number for the amount of days a package will take to reach #its destination.

usps.express_mail_commitment(origin, destination, date=nil)

#returns a array of hashs containing commitment information. Example shown below

[{:state=>"MD", :cutoff=>"6:00 PM", :facility=>"EXPRESS MAIL COLLECTION BOX", :zip=>"20770", :street=>"119 CENTER WAY", :city=>"GREENBELT"}, {:state=>"MD", :cutoff=>"3:00 PM", :facility=>"EXPRESS MAIL COLLECTION BOX", :zip=>"20770", :street=>"7500 GREENWAY CENTER DRIVE", :city=>"GREENBELT"}]

#Label APIs #All label API's generate a label image encoded via 64bit encryption. It must be decrypted by using #Base64.decode64(Image_file) to display correctly. The only choices for image_type right now are pdf and TIFF

#An easy way to test and intergrate is to set up something along these lines in a controller.

def deliver_confirmation image = USPS.new("XXXXXX").canned_delivery_confirmation_label_test send_data Base64.decode64(image[:label]), :type => image[:image_type], :disposition => "inline" end

#All labels except for international labels take a straight name for their XML. #When using International label APIs you must include both a first and last name

usps.delivery_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={}) usps.signature_confirmation_label(origin, destination, service_type, image_type, label_type=1, options={})

#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you, #you simply will receive a confirmation label to use with the image you create.

#Option hash can contain

• :weight_in_ounces
• :seperate => puts the label directions on a seperate page.
• :po_zip_code => Post Offic zip code
• :label_date => Can be set up to four days in the future
• :customer_reference_number
• :address_service => ill be notified in the future if address has been changed
• :sender_name, :sender_email, :recipient_name, :recipient_email => Used together to send an email to the recipient.

usps.merch_return(service_type, customer, retailer, permit_number, post_office, postage_delivery_unit, ounces, image_type, options={})

#permit_number => Input permit number provided by your local post office. #post_office => Location class of post office that issued the permit. Address not needed #postage_delivery_unit => Location class for delivery unit you are sending the package to.

#Option hash can contain

• :confirmation => "Includes delivery confirmation with the label. To enable set to true"
• :insurance_value
• :rma => "Return Materials Authorization Number"
• :RMABarcode => "Will Render Barcode on Label if set to true and a RMA has been entered"
• :sender_name, :sender_email, :recipient_name, :recipient_email => Used together to send an email to the recipient.

#Output hash contains postnet number and the cost for sending. Under :postnet and :cost respectively.

usps.express_mail_label(orgin, destination, ounces, image_type, options={})

#Option hash can contain

• :flat_rate => "Can be set to true if using flat rate envelopes"
• :standardize_address => "Verify Address"
• :waiver_signature => "No Signature Required for Delivery"
• :no_holiday => "Do not deliver on a holiday"
• :no_weekend
• :seperate => puts the label directions on a seperate page
• :po_zip_code
• :label_date => Can be set up to four days in the future
• :sender_name, :sender_email, :recipient_name, :recipient_email => Used together to send an email to the recipient.

#Output hash contains postage cost for sending. Can be accessed by :postage

usps.express_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N", image_layout="ALLINONEFILE", label_type="1", options={})

usps.priority_mail_international_label(sender, receiver, items, image_type, po_box_flag ="N", image_layout="ALLINONEFILE", label_type="1", options={})

usps.first_class_international_label(sender, receiver, items, image_type, po_box_flag ="N", image_layout="ALLINONEFILE", label_type="1", options={})

#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you, #items => InternationalItem.new can be an array of objects or singular #content_type => Options are "MERCHANDISE", "SAMPLE", "GIFT", "DOCUMENTS", "RETURN", "OTHER" #If OTHER is selected content type must be described by :other => "Description" in the option hash. #image_layout => "Allows for a few options" #po_box_flag can be set to "Y" if items are being sent to a PO-Box

Option Hash for priority and express can contain

• :middle_initial => "middle initial of sender"
• :from_customs_reference
• :to_customs_reference
• :fax => "fax of receiver"
• :email => "email of receiver"
• :non_delivery_option => "Return, Reject, Abaddon. Defaults to abaddon."
• :alt_return_address1 => "used to explain where package goes if delivery_option set to . Goes up to alt_return_address6"
• :alt_return_country
• :container => "VARIABLE or FLATRATEENV"
• :insurance_number
• :Postage => "If postage is already known. Will be caculated if left blank. "
• :other
• :comments
• :license_number
• :certificate_number
• :invoice_number
• :reference_number
• :po_zip_code
• :label_date => Can be set up to four days in the future
• :hold => "Hold for manifest"

Option Hash for first_class can contain

• :middle_initial => "middle initial of sender"
• :from_customs_reference
• :to_customs_reference
• :fax => "fax of receiver"
• :email => "email of receiver"
• :first_class_mail_type
• :machinable => "True or False"
• :other
• :comments
• :label_date => Can be set up to four days in the future
• :hold => "Hold for manifest"

#Output hash contains postage cost, total value of all items, SDRValue and the Bar code number. #Can be access :postage, :totalvalue, :sdrvalue, and :barcodenumber respectively.

96.25 16.65 11.42 LJ000100644US

#TODO a good description for what Open Distribute Priority actually means

usps.open_distrubute_priority_label(orgin, destination, package_weight_in_ounces, mail_type, image_type, label_type=1, options={})

#label_type can be set to 2 if you desire to create your own labels. No label will be generated for you, #you simply will receive a confirmation label to use with the image you create.

#destination class must contain :facility_type, See API Document for explination of the different types

#mail_type can be be, "Letters", "Flats", "Parcels", "Mixed" or "Other" #If other is chosen it must be described in the option hash via :other => "Description"

#Option has can contain

• :permit_number => "Issued by Post Office"
• :permit_zip => "Zip of Post Office that issued permit. Must be included if using :permit_number"
• :po_zip_code
• :other
• :no_weekend
• :seperate => puts the label directions on a seperate page
• :label_date => Can be set up to four days in the future

• Proofread documentation
• Add tests with RSPEC

Yes, please! I am a young Ruby Developer who is making plenty mistakes. Any improvements to the coding structure or patches would be highly appreciated.

The nicest way to submit changes would be to set up a GitHub account and fork this project, then initiate a pull request when you want your changes looked at. You can also make a patch (preferably with git-diff) and email to [email protected]

Unless otherwise noted in specific files, all code in the Awesome USPS is under the copyright and license described in the included MIT-LICENSE file.

Packages Module created by James MacAulay

Copyright (c) 2008 Matthew Bergman, released under the MIT license