Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Simple and straight forward interfaces to the various shipping web services
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



The goal of this library is to provide simple and straight forward interfaces to the various shipping web services: FedEx, UPS, USPS, etc. (Only FedEx is supported at this time)

Helpful links

Before contacting me directly, please read:

If you find a bug or a problem please post it on lighthouse. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.

Install & use

Install the gem from rubyforge:

sudo gem install shippinglogic

Or from github:

sudo gem install binarylogic-shippinglogic

Now just include it in your project and you are ready to go.

You can also install this as a plugin:

script/plugin install git://

See below for usage examples.


What's unique about this library is it's usage / syntax. Let me show you…

Calls to the web services are lazy

A simple example where we want to track a FedEx package:

fedex =, password, account, meter) # all credentials FedEx requires
tracking = fedex.track(:tracking_number => "077973360403984")

Now here is why this is cool. Nothing has happened yet. No call has been made to the FedEx servers, etc. We do this because we don't need it yet. You don't need it until you start using the object. Lets continue with our example:

tracking.first  # call is made to FedEx and returns the first tracking result in the array
tracking.size   # cache is used to determine the size of the array

This is similar to how ActiveRecord's association proxies work. When you call user.orders no database activity occurs until you actually use the object.


You will notice above we assign the result of the 'track' method to a variable called 'tracking'. That object has more to it:

# Initializing
tracking = fedex.track(:tracking_number => "XXXXXXXXXXXXX")

# Attribute accessors
tracking.tracking_number = "YYYYYYYYYYYYYYY"

# Mass attribute setting
tracking.attributes = {:tracking_number => "ZZZZZZZZZZZZZZZZ"}

# Mass attribute reading
# => {:tracking_number => "ZZZZZZZZZZZZZZZZ"}

Available services and their features

This library is still very new, as a result only FedEx is support at this time. More will come.


  1. Tracking - See Shippinglogic::Fedex::Track

  2. Getting service rates - See Shippinglogic::Fedex::Rates

Add your own services

Simply fork the project and make your changes. If you want to add support for a new service it should be fairly straight forward. Checkout the code in Shippinglogic::Fedex::Track, it very simple and easy to follow. It's a great place to start because its the simplest of services.

Interface integration

What's nice about having an object is that you can pass it around. Let's say you wanted to add simple FedEx tracking functionality to your app:

class TrackingController < ApplicationController
  def new
    @tracking = fedex.track(params[:tracking])

  def create
    @tracking = fedex.track(params[:tracking])
    render :action => :new if !@tracking.successful?

    def fedex
      @fedex ||=, password, account, meter)

That's pretty simple. Now check out your form:

# new.html.haml
- form_for @tracking do |f|
  = f.error_messages
  = f.text_field :tracking_number
  = f.submit "Track"

Then your results:

# create.html.haml
- @tracking.each do |event|
    .occured_at= event.occured_at.to_s(:long)
    .location== #{}, #{event.state} #{event.postal_code}, #{}
    .residential= event.residential ? "Yes" : "No"


Copyright © 2009 Ben Johnson of Binary Logic, released under the MIT license

Something went wrong with that request. Please try again.