Class: Trackerific::USPS

Inherits:
Service show all
Includes:
HTTParty
Defined in:
lib/trackerific/services/usps.rb

Overview

Provides package tracking support for USPS.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from Service

#initialize

Methods included from OptionsHelper

#validate_options

Constructor Details

This class inherits a constructor from Trackerific::Service

Class Method Details

+ (Array, Regexp) package_id_matchers

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

An Array of Regexp that matches valid USPS package IDs

Returns:

  • (Array, Regexp) —

    the regular expression 



22
23
24
 
# File 'lib/trackerific/services/usps.rb', line 22

def package_id_matchers
  [ /^E\D{1}\d{9}\D{2}$|^9\d{15,21}$/ ]
end

+ (Array) required_options

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The required options for tracking a UPS package

Returns:

  • (Array) —

    the required options for tracking a UPS package 



29
30
31
 
# File 'lib/trackerific/services/usps.rb', line 29

def required_options
  [:user_id]
end

Instance Method Details

- (Trackerific::Details) track_package(package_id)

Tracks a USPS package

Examples:

Track a package 

usps = Trackerific::USPS.new user_id: 'user'
details = ups.track_package("EJ958083578US")

Parameters:

  • package_id (String) —

    the package identifier

Returns:

Raises:

  • (Trackerific::Error) —

    raised when the server returns an error (invalid credentials, tracking package, etc.) 



42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/trackerific/services/usps.rb', line 42

def track_package(package_id)
  super
  # connect to the USPS shipping API via HTTParty
  response = self.class.get('/ShippingAPITest.dll', :query => {:API => 'TrackV2', :XML => build_xml_request}.to_query)
  # throw any HTTP errors
  response.error! unless response.code == 200
  # raise a Trackerific::Error if there is an error in the response, or if the
  # tracking response is malformed
  raise Trackerific::Error, response['Error']['Description'] unless response['Error'].nil?
  raise Trackerific::Error, "Tracking information not found in response from server." if response['TrackResponse'].nil?
  # get the tracking information from the response, and convert into a
  # Trackerific::Details
  tracking_info = response['TrackResponse']['TrackInfo']
  details = []
  tracking_info['TrackDetail'].each do |d|
    # each tracking detail is a string in this format:
    # MM DD HH:MM am/pm DESCRIPTION CITY STATE ZIP.
    # unfortunately, it will not be possible to tell the difference between
    # the location, and the summary. So, for USPS, the location will be in
    # the summary
    d = d.split(" ")
    date = DateTime.parse(d[0..3].join(" "))
    desc = d[4..d.length].join(" ")
    details << Trackerific::Event.new(date, desc, "")
  end
  # return the details
  Trackerific::Details.new(
    tracking_info['ID'],
    tracking_info['TrackSummary'],
    details
  )
end