Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 173 lines (131 sloc) 8.826 kb
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
1 # Active Shipping
2
3 This library is meant to interface with the web services of various shipping carriers. The goal is to abstract the features that are most frequently used into a pleasant and consistent Ruby API. Active Shipping is an extension of [Active Merchant][], and as such, it borrows heavily from conventions used in the latter.
4
5 We are starting out by only implementing the ability to list available shipping rates for a particular origin, destination, and set of packages. Further development could take advantage of other common features of carriers' web services such as tracking orders and printing labels.
6
7 Active Shipping is currently being used and improved in a production environment for the e-commerce application [Shopify][]. Development is being done by [James MacAulay][] (<james@jadedpixel.com>). Discussion is welcome in the [Active Merchant Google Group][discuss].
8
9 [Active Merchant]:http://www.activemerchant.org
10 [Shopify]:http://www.shopify.com
11 [James MacAulay]:http://jmacaulay.net
12 [discuss]:http://groups.google.com/group/activemerchant
13
14 ## Supported Shipping Carriers
15
16 * [UPS](http://www.ups.com)
17 * [USPS](http://www.usps.com)
d78664b @jamesmacaulay added FedEx to list of supported carriers
jamesmacaulay authored
18 * [FedEx](http://www.fedex.com)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
19 * more soon!
20
21 ## Prerequisites
22
23 * [active_support](http://github.com/rails/rails/tree/master/activesupport)
24 * [xml_node](http://github.com/tobi/xml_node/) (right now a version of it is actually included in this library, so you don't need to worry about it yet)
25 * [mocha](http://mocha.rubyforge.org/) for the tests
26
27 ## Download & Installation
28
29 Currently this library is available on GitHub:
30
7f06401 @jamesmacaulay Proper git clone URL
jamesmacaulay authored
31 <http://github.com/Shopify/active_shipping>
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
32
33 You will need to get [Git][] if you don't have it. Then:
34
7f06401 @jamesmacaulay Proper git clone URL
jamesmacaulay authored
35 > git clone git://github.com/Shopify/active_shipping.git
36
37 (That URL is case-sensitive, so watch out.)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
38
39 Active Shipping includes an init.rb file. This means that Rails will automatically load it on startup. Check out [git-archive][] for exporting the file tree from your repository to your vendor directory.
40
41 Gem and tarball forthcoming on rubyforge.
42
43 [Git]:http://git.or.cz/
44 [git-archive]:http://www.kernel.org/pub/software/scm/git/docs/git-archive.html
45
46 ## Sample Usage
47
48 require 'active_shipping'
49 include ActiveMerchant::Shipping
50
51 # Package up a poster and a Wii for your nephew.
52 packages = [
53 Package.new( 100, # 100 grams
54 [93,10], # 93 cm long, 10 cm diameter
55 :cylinder => true), # cylinders have different volume calculations
56
57 Package.new( (7.5 * 16), # 7.5 lbs, times 16 oz/lb.
58 [15, 10, 4.5], # 15x10x4.5 inches
59 :units => :imperial) # not grams, not centimetres
60 ]
61
62 # You live in Beverly Hills, he lives in Ottawa
63 origin = Location.new( :country => 'US',
64 :state => 'CA',
65 :city => 'Beverly Hills',
66 :zip => '90210')
67
68 destination = Location.new( :country => 'CA',
69 :province => 'ON',
70 :city => 'Ottawa',
71 :postal_code => 'K1P 1J1')
72
73 # Find out how much it'll be.
74 ups = UPS.new(:login => 'auntjudy', :password => 'secret', :key => 'xml-access-key')
75 response = ups.find_rates(origin, destination, packages)
76
77 ups_rates = response.rates.sort_by(&:price).collect {|rate| [rate.service_name, rate.price]}
78 # => [["UPS Standard", 3936],
79 # ["UPS Worldwide Expedited", 8682],
80 # ["UPS Saver", 9348],
81 # ["UPS Express", 9702],
82 # ["UPS Worldwide Express Plus", 14502]]
83
84 # Check out USPS for comparison...
85 usps = USPS.new(:login => 'developer-key')
86 response = usps.find_rates(origin, destination, packages)
87
88 usps_rates = response.rates.sort_by(&:price).collect {|rate| [rate.service_name, rate.price]}
89 # => [["USPS Priority Mail International", 4110],
90 # ["USPS Express Mail International (EMS)", 5750],
91 # ["USPS Global Express Guaranteed Non-Document Non-Rectangular", 9400],
92 # ["USPS GXG Envelopes", 9400],
93 # ["USPS Global Express Guaranteed Non-Document Rectangular", 9400],
94 # ["USPS Global Express Guaranteed", 9400]]
64a1348 FedEx carrier class now returns rates for both Ground and Express servic...
Jimmy Baker authored
95
96 # FedEx
6cd0129 FedEx#find_tracking_info is working. Added Sample Usage to the README.
Jimmy Baker authored
97 fdx = FedEx.new(:login => 'Your 9-digit FedEx Account #', :password => 'Your Meter Number')
64a1348 FedEx carrier class now returns rates for both Ground and Express servic...
Jimmy Baker authored
98 response = fdx.find_rates(origin, destination, packages, :test => true)
99 response.rates.sort_by(&:price).collect {|rate| [rate.service_name, rate.price]}
1c84842 Updated README documentation for FedEx usage.
Jimmy Baker authored
100 # => [["FedEx Ground", 977],
101 # ["FedEx Ground Home Delivery", 1388],
102 # ["FedEx Express Saver", 2477],
103 # ["FedEx 2 Day", 2718],
104 # ["FedEx Standard Overnight", 4978],
105 # ["FedEx Priority Overnight", 8636],
106 # ["FedEx First Overnight", 12306]]
64a1348 FedEx carrier class now returns rates for both Ground and Express servic...
Jimmy Baker authored
107
6cd0129 FedEx#find_tracking_info is working. Added Sample Usage to the README.
Jimmy Baker authored
108 # FedEx Tracking
109 fdx = FedEx.new(:login => '999999999', :password => '7777777')
110 tracking_info = fdx.find_tracking_info('tracking number here', :carrier_code => 'fedex_ground') # Ground package
111
112 tracking_info.shipment_events.each do |event|
113 puts "#{event.name} at #{event.location.city}, #{event.location.state} on #{event.time}. #{event.message}"
114 end
115 # => Package information transmitted to FedEx at NASHVILLE LOCAL, TN on Thu Oct 23 00:00:00 UTC 2008.
116 # Picked up by FedEx at NASHVILLE LOCAL, TN on Thu Oct 23 17:30:00 UTC 2008.
117 # Scanned at FedEx sort facility at NASHVILLE, TN on Thu Oct 23 18:50:00 UTC 2008.
118 # Departed FedEx sort facility at NASHVILLE, TN on Thu Oct 23 22:33:00 UTC 2008.
119 # Arrived at FedEx sort facility at KNOXVILLE, TN on Fri Oct 24 02:45:00 UTC 2008.
120 # Scanned at FedEx sort facility at KNOXVILLE, TN on Fri Oct 24 05:56:00 UTC 2008.
121 # Delivered at Knoxville, TN on Fri Oct 24 16:45:00 UTC 2008. Signed for by: T.BAKER
122
123 tracking_info = fdx.find_tracking_info('tracking number here', :carrier_code => 'fedex_express') # Express package
124
125 tracking_info.shipment_events.each do |event|
126 puts "#{event.name} at #{event.location.city}, #{event.location.state} on #{event.time}. #{event.message}"
127 end
128 # => Picked up by FedEx at NASHVILLE, TN on Wed Dec 03 16:46:00 UTC 2008.
129 # Package status at MISSISSAUGA, ON on Wed Dec 03 18:00:00 UTC 2008.
130 # Left FedEx Origin Location at NASHVILLE, TN on Wed Dec 03 20:27:00 UTC 2008.
131 # Arrived at FedEx Ramp at NASHVILLE, TN on Wed Dec 03 20:43:00 UTC 2008.
132 # Left FedEx Ramp at NASHVILLE, TN on Wed Dec 03 22:30:00 UTC 2008.
133 # Arrived at Sort Facility at INDIANAPOLIS, IN on Thu Dec 04 00:31:00 UTC 2008.
134 # Left FedEx Sort Facility at INDIANAPOLIS, IN on Thu Dec 04 01:14:00 UTC 2008.
135 # Left FedEx Sort Facility at INDIANAPOLIS, IN on Thu Dec 04 04:48:00 UTC 2008.
136 # Arrived at FedEx Ramp at MISSISSAUGA, ON on Thu Dec 04 06:26:00 UTC 2008.
137 # Package status at MISSISSAUGA, ON on Thu Dec 04 07:03:00 UTC 2008.
138 # Left FedEx Ramp at MISSISSAUGA, ON on Thu Dec 04 07:37:00 UTC 2008.
139 # Arrived at FedEx Destination Location at TORONTO, ON on Thu Dec 04 08:42:00 UTC 2008.
140 # On FedEx vehicle for delivery at TORONTO, ON on Thu Dec 04 09:04:00 UTC 2008.
141 # Delivered to Non-FedEx clearance broker at TORONTO, ON on Thu Dec 04 10:15:00 UTC 2008.
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
142
143 ## TODO
144
145 * proper documentation
146 * proper offline testing for carriers in addition to the remote tests
147 * package into a gem
148 * carrier code template generator
149 * more carriers
150 * integrate with ActiveMerchant
151 * support more features for existing carriers
152 * bin-packing algorithm (preferably implemented in ruby)
153 * order tracking
154 * label printing
155
156 ## Contributing
157
158 Yes, please! Take a look at the tests and the implementation of the Carrier class to see how the basics work. At some point soon there will be a carrier template generator along the lines of the gateway generator included in Active Merchant, but carrier.rb outlines most of what's necessary. The other main classes that would be good to familiarize yourself with are Location, Package, and Response.
159
160 The nicest way to submit changes would be to set up a GitHub account and fork this project, then initiate a pull request when you want your changes looked at. You can also make a patch (preferably with [git-diff][]) and email to james@jadedpixel.com.
161
162 [git-diff]:http://www.kernel.org/pub/software/scm/git/docs/git-diff.html
163
164 ## Contributors
165
428e933 @jamesmacaulay added attribution info
jamesmacaulay authored
166 * James MacAulay (<http://jmacaulay.net>)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
167 * Tobias Luetke (<http://blog.leetsoft.com>)
168 * Cody Fauser (<http://codyfauser.com>)
428e933 @jamesmacaulay added attribution info
jamesmacaulay authored
169 * Jimmy Baker (<http://jimmyville.com/>)
0eebee7 @jamesmacaulay first commit
jamesmacaulay authored
170
171 ## Legal Mumbo Jumbo
172
173 Unless otherwise noted in specific files, all code in the Active Shipping project is under the copyright and license described in the included MIT-LICENSE file.
Something went wrong with that request. Please try again.