gaffneyc / usps

USPS Webtools API for Ruby
MIT License
63 stars 54 forks source link

usps

Gem Version Run tests

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

Testing

bundle exec rspec

Further Reading

Copyright

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