Trackerific provides USPS, FedEx and UPS package tracking to Rails.
Pull request Compare This branch is 13 commits ahead, 44 commits behind travishaynes:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



To use this gem, add this line to your Gemfile

gem 'trackerific'

and then run

bundle install


If you would like to see a functional example of this gem in action, check out the sample Rails app here: package-tracker


To take advantage of Trackerific's automatic service discovery, you will need to configure your credentials for each service.

# config/initializers/trackerific.rb
require 'trackerific'
Trackerific.configure do |config|  :account  => 'account',
                :meter    => '123456789'    :key      => 'key',
                :user_id  => 'userid',
                :password => 'secret'

  config.usps   :user_id  => 'userid',
                :use_city_state_lookup => true

For USPS packages, the option :use_city_state_lookup defaults to false, and will only work if you have access to USPS's CityStateLookup API. If you can enable it, this feature will provide the location for USPS package events.

Tracking with Automatic Service Discovery

Once you configured the services, tracking a package is as easy as

include Trackerific
details = track_package "package id"

Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id, or you used track_package, and you need to know which service was used to track it, you can use the tracking_service helper method.

include Trackerific
tracking_service "183689015000001"    # => Trackerific::FedEx
tracking_service "1Z12345E0291980793" # => Trackerific::UPS
tracking_service "EJ958083578US"      # => Trackerific::USPS
tracking_service "unknown package id" # => nil

Tracking a Package with a Specific Service

Use this method if you need to specify exactly which service to track a package.

# Track a FedEx package:
fedex = :account => '123456789', :meter => '123456789'
details = fedex.track_package('183689015000001')

# Track a USPS package:
usps = :user_id => '123USERID4567'
details = usps.track_package('EJ958083578US')

# Track a UPS package:
ups = :user_id => 'userid', :key => 'kQdEJwuHBjtQ7g2', :password => 'secret'
details = ups.track_package('1Z12345E0291980793')

Tracking Details

The tracking information is returned in a Trackerific::Details instance.

details.summary # => a summary of the tracking events  # => an Array of Trackerific::Events

You can easily print out the tracking events just by doing:

puts         # for all the events
puts   # for just one event

Or, if you need specific information about an event:         # => the date the package was shipped        # => the last date the package was updated # => a description of an event    # => the location of the package during that event

location will not work for USPS packages, because USPS does not provide that information seperately from the description. So for USPS packages, the location will always be at the end of the description.

Note that events.last will return the first event the tracking provider supplied. This is because the events are listed in LIFO order, so the most recent events will always be at the top of the list.

City / State Lookup Via USPS

If you have access to the USPS CityStateLookup API, you can use Trackerific to look up the city and state of a zipcode.

usps = :user_id => 'userid'
usps.city_state_lookup "90210" # => { :city => 'BEVERLY HILLS', :state => 'CA', :zip => '90210' }

Exception handling

Exception handling is esssential for tracking packages. If, for example, you enter the wrong number, or the tracking provider has yet to have added the tracking number to their system, a Trackerific::Error will be raised. Here's an example on how to handle Trackerific::Errors:

rescue Trackerific::Error => e
  puts e.message

or for a Rails application:

# in app/controllers/application_controller.rb
rescue_from Trackerific::Error do |exception|
  redirect_to root_url, :alert => exception.message

Writing a Custom Service

See the examples folder for an example of a custom service.

Testing with Trackerific

Trackerific provides a mocked service you can use in your unit tests of your application. The mocked service will be available in development and test environments only, and disabled in production.

details = track_package("XXXXXXXXXX") # => returns a populated Trackerific::Details
details = track_package("XXXxxxxxxx") # => throws a Trackerific::Errror exception

Contributing to trackerific

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.


Copyright © 2011 Travis Haynes. See LICENSE.txt for further details.