Installation

To use this gem, add this line to your Gemfile

gem 'trackerific'

and then run

bundle install

Configuration

You will need to configure your credentials for each service:

Trackerific.configure do |config|
  config.fedex  :account  => 'account',
                :meter    => '123456789'

  config.ups    :key      => 'key',
                :user_id  => 'userid',
                :password => 'secret'

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

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

details = Trackerific.track("package id")

Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id you can use Trackerific::Services.find_by_tracking_id:

Trackerific::Services.find_by_tracking_id("183689015000001")    # => Trackerific::Services::FedEx
Trackerific::Services.find_by_tracking_id("1Z12345E0291980793") # => Trackerific::Services::UPS
Trackerific::Services.find_by_tracking_id("EJ958083578US")      # => Trackerific::Services::USPS
Trackerific::Services.find_by_tracking_id("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:
details = Trackerific::Services::FedEx.track('183689015000001')

# Track a USPS package:
details = Trackerific::Services::USPS.track('EJ958083578US')

# Track a UPS package:
details = Trackerific::Services::UPS.track('1Z12345E0291980793')

Using #track will automatically read the credentials from ‘Trackerific.configuration`. If you need to assign them manually, use #new:

fedex = Trackerific::Services::FedEx.new account: "account", meter: "123456789"
details = fedex.track('183689015000001')

Tracking Details

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

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

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

puts details.events         # for all the events
puts details.events.first   # for just one event

Or, if you need specific information about an event:

details.events.last.date         # => the date the package was shipped
details.events.first.date        # => the last date the package was updated
details.events.first.description # => a description of an event
details.events.first.location    # => 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 = Trackerific::Services::USPS.new :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:

begin
  details = Trackerific.track('EJ958083578US')
  # handle details here
rescue Trackerific::Error => e
  puts e.message
end

Testing

Trackerific provides a mocked service you can use in your unit tests of your application. You must require the service manually.

require 'trackerific/services/mock_service'
details = track_package("XXXXXXXXXX") # => returns a populated Trackerific::Details
details = track_package("XXXxxxxxxx") # => throws a Trackerific::Error exception

Contributing

  1. Fork it

  2. Create your feature branch (‘git checkout -b my-new-feature`)

  3. Commit your changes (‘git commit -am ’Add some feature’‘)

  4. Push to the branch (‘git push origin my-new-feature`)

  5. Create new Pull Request