File: README — Documentation by YARD 0.7.1

Installation:

To use this gem, add this line to your Gemfile

  gem 'trackerific'

and then run

  bundle install

Usage:

  # Track a FedEx package:
  fedex = Trackerific::FedEx.new :account => '123456789', :meter => '123456789'
  details = fedex.track_package('183689015000001')
  
  # Track a USPS package:
  usps = Trackerific::USPS.new :user_id => '123USERID4567'
  details = usps.track_package('EJ958083578US')
  
  # Track a UPS package:
  ups = Trackerific::UPS.new :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
  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.

Finding a Tracking Service Provider

If you do not know the tracking service provider of a package id, you can use the tracking_service helper method to get a Trackerific class that most likely will be able to track the given package id.

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

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
    usps.track_package('EJ958083578US')
  rescue Trackerific::Error => e
    puts e.message
  end

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