gaffneyc / usps

USPS Webtools API for Ruby

usps

Ruby API for accessing the USPS WebTools API found here: https://www.usps.com/business/webtools.htm

PDF Guides can be found here: https://www.usps.com/business/webtools-technical-guides.htm

Usage of this library assumes you already have a USPS API account and that all privileges have been granted.

Exposed API Calls

The following USPS API calls are currently exposed through this library:

<AddressValidateRequest>             -- USPS::Request::AddressStandardization
<CityStateLookupRequest>             -- USPS::Request::CityAndStateLookup
<ZipCodeLookupRequest>               -- USPS::Request::ZipCodeLookup
<TrackRequest>                       -- USPS::Request::TrackingLookup
<TrackFieldRequest>                  -- USPS::Request::TrackingFieldLookup

<DeliveryConfirmationV3.0Request>    -- USPS::Request::DeliveryConfirmation        (for production)
<DeliveryConfirmCertifyV3.0Request>  -- USPS::Request::DeliveryConfirmationCertify (for testing)

Usage

Using the library is as simple as building a new USPS::Request::[type] object, calling #send! and using the response. For example, to send a tracking request you'd do the following:

USPS.username = "XXXXXX" # your USPS API username, or set ENV['USPS_USER']
request = USPS::Request::TrackingLookup.new(tracking_number)
response = request.send!

response.summary
response.details

The library assumes that either ENV['USPS_USER'] is set, or that you set USPS.username to your USPS API username.

See the individual USPS::Request classes for details on how to use them.

Address Validation

require 'usps'

USPS.config.username = 'YOUR USERNAME'

address = USPS::Address.new(address1: '1 Times Square', city: 'New York', state: 'NY')
req = USPS::Request::AddressStandardization.new(address)
response = req.send!
response.get(address)
#<#<Class:0x00007fc6f3c4b870>:USPS::Address:0x00495ef8
  address1 = "1 TIMES SQ",
  address2 = "",
  city = "NEW YORK",
  company = "",
  name = nil,
  return_text = "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address.",
  state = "NY",
  zip4 = "6560",
  zip5 = "10036"

USPS API Certification

Part of the process of setting up an account with the USPS API is to run certain tests against the USPS API. This library has all the requisite tests built in, runnable with rake:

USPS_USER="[username]" bundle exec rake certify

or as an installed gem:

USPS_USER="[username]" bundle exec ruby -e "require 'usps/test'"

If any of the tests fail, you don't have access to that API and may need to work with USPS to fix it.

Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

Testing

bundle exec rspec

Further Reading

• USPS API docs
• 18F's USPS API Notes

Copyright

Copyright (c) 2014 Chris Gaffney. See LICENSE for details.

usps's Issues

Release v1.0

This is to track the path to releasing a version 1.0 of this gem. The gem is currently fully functional and usable. The benefits of releasing a 1.0 are largely practical in that it gives more room for semantic versioning.

Problem with `rake certify`

No runtime errors, but some failing tests:

➜  usps git:(add_shipping_labels) bundle exec rake certify
/Users/alandelevie/.rbenv/versions/2.1.5/bin/ruby -rubygems -Ilib lib/usps/test.rb
Run options: 

# Running tests:

[1/8] USPS::Test#test_address_standardization_1 = 0.19 s
  1) Failure:
USPS::Test#test_address_standardization_1 [/Users/alandelevie/usps/lib/usps/test/address_verification.rb:14]:
<"1440"> expected but was
<"1441">.

[5/8] USPS::Test#test_tracking_lookup_1 = 0.21 s                
  2) Failure:
USPS::Test#test_tracking_lookup_1 [/Users/alandelevie/usps/lib/usps/test/tracking_lookup.rb:8]:
<"Your item was delivered at 8:10 am on June 1 in Wilmington DE 19801."> expected but was
<"There is no record of that mail item. If it was mailed recently, it may not yet be tracked. Please try again later.">.

[6/8] USPS::Test#test_tracking_lookup_2 = 0.20 s        
  3) Failure:
USPS::Test#test_tracking_lookup_2 [/Users/alandelevie/usps/lib/usps/test/tracking_lookup.rb:21]:
<"Your item was delivered at 1:39 pm on June 1 in WOBURN MA 01815."> expected but was
<"There is no record of that mail item. If it was mailed recently, it may not yet be tracked. Please try again later.">.

[7/8] USPS::Test#test_zip_code_lookup_1 = 0.12 s        
  4) Failure:
USPS::Test#test_zip_code_lookup_1 [/Users/alandelevie/usps/lib/usps/test/zip_code_lookup.rb:17]:
<"1440"> expected but was
<"1441">.

Finished tests in 1.065323s, 7.5095 tests/s, 26.2831 assertions/s.
8 tests, 28 assertions, 4 failures, 0 errors, 0 skips

ruby -v: ruby 2.1.5p273 (2014-11-13 revision 48405) [x86_64-darwin13.0]
rake aborted!
Command failed with status (4): [/Users/alandelevie/.rbenv/versions/2.1.5/b...]
/Users/alandelevie/usps/Rakefile:9:in `block in <top (required)>'
Tasks: TOP => certify
(See full trace by running task with --trace)

I'm wondering if the test expectations should just be updated. Thoughts, @gaffneyc?

Move from Travis to GH Actions

Travis is undergoing a migration in May from their .org to .com product. I've been using Github Actions on several other gems and projects with great success. I find the integration on GH Actions to be smoother and caching/builds to be faster.

Rate API changed

V3 is deprecated in favor of V4.

See also: 2014-rate-webtools-v3-v4-transition-guide.rtf

400 Error

This gem started to return the HTTP 400 error on every request.

Timeout issue

When we send a Timeout request, we will get empty response body

 response = Typhoeus::Request.get(server, {
        :timeout => USPS.config.timeout,
        :params => {
          "API" => request.api,
          "XML" => request.build
        }
      })

response.body # => ""

So, when I send the request to verify the address it will not raise error with the error address. We probably get different result by the same request. Sometimes will raise AddressNotFoundError and sometimes will not get any feedback.

I think it will be better to raise the TimeoutError, when the request timeout.

Remove support for EOL Ruby versions

This gem currently targets Ruby versions 1.9.3 - 2.1. These versions have been end-of-lifed as of 2015 - 2017, respectively.

Currently maintained Ruby versions are 2.6 - 3.0.

Forward-looking changes, that likely would be backwards incompatible, would be Ruby 2 style hashes and kwargs.