Class: Trackerific::Services::USPS

Inherits:
Base
  • Object
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 Base

can_track?, register, track

Constructor Details

#initialize(options = {}) ⇒ USPS

Returns a new instance of USPS.



18
19
20
 
# File 'lib/trackerific/services/usps.rb', line 18

def initialize(options={})
  @options = options
end

Class Method Details

.package_id_matchers ⇒ Array, Regexp

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



25
26
27
 
# File 'lib/trackerific/services/usps.rb', line 25

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

Instance Method Details

#city_state_lookup(zipcode) ⇒ Hash

Gets the city/state of a zipcode - requires access to USPS address APIs

Examples:

Lookup zipcode for Beverly Hills, CA

usps = Trackerific::USPS.new :user_id => 'youruserid'
city_state = usps.city_state_lookup(90210)
city_state[:city]  # => BEVERLY HILLS
city_state[:state] # => CA
city_state[:zip]   # => 90210

Parameters:

  • zipcode (String) —

    The zipcode to find the city/state for

Returns:

  • (Hash) —

    { zip: ‘the zipcode, ’city: “the city”, state: “the state” }



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/trackerific/services/usps.rb', line 76

def city_state_lookup(zipcode)
  response = self.class.get(
    env == 'production' ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
    query: {
      :API => 'CityStateLookup',
      :XML => build_city_state_xml_request(zipcode)
    }.to_query
  )
  # raise any errors
  error = check_response_for_errors(response, :CityStateLookup)
  raise error unless error.nil?
  # return the city, state, and zip
  response = response['CityStateLookupResponse']['ZipCode']
  {
    :city   => response['City'],
    :state  => response['State'],
    :zip    => response['Zip5']
  }
end

#track(id) ⇒ Trackerific::Details

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.)



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/trackerific/services/usps.rb', line 37

def track(id)
  @package_id = id
  # connect to the USPS shipping API via HTTParty
  response = self.class.get(
    env == 'production' ? "/ShippingAPI.dll" : "/ShippingAPITest.dll",
    query: { :API => 'TrackV2', :XML => build_tracking_xml_request }.to_query
  )
  # raise any errors
  error = check_response_for_errors(response, :TrackV2)
  raise error unless error.nil?
  # get the tracking information from the response
  tracking_info = response['TrackResponse']['TrackInfo']
  events = []
  # parse the tracking events out of the USPS tracking info
  tracking_info['TrackDetail'].each do |d|
    events << Trackerific::Event.new(
      date_of_event(d),
      description_of_event(d),
      location_of_event(d)
    )
  end unless tracking_info['TrackDetail'].nil?
  # return the details
  Trackerific::Details.new(
    tracking_info['ID'],
    tracking_info['TrackSummary'],
    events
  )
end