Class: CTA::BusTracker

Inherits:
Object
  • Object
show all
Defined in:
lib/cta_redux/bus_tracker.rb,
lib/cta_redux/api/bus_tracker.rb,
lib/cta_redux/faraday_middleware/bus_tracker_parser.rb

Defined Under Namespace

Classes: Direction, DirectionsResponse, Parser, Pattern, PatternsResponse, Point, PredictionsResponse, RoutesResponse, Service, ServiceBulletin, ServiceBulletinsResponse, StopsResponse, TimeResponse, VehiclesResponse

Class Method Summary collapse

Class Method Details

.bulletins!(options = {}) ⇒ CTA::BusTracker::ServiceBulletinsResponse

Note:

Consider using CustomerAlerts.alerts! or CustomerAlerts.status!, as those are not rate-limited.

Returns active bulletins.

Examples:

CTA::BusTracker.bulletins!(:routes => [8, 22])

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :routes (Array<String>, Array<Integer>, String, Integer) —

    Routes for which to retrieve bulletins. When combined with :direction or :stops, may only specify one :route.

  • :direction (String, Integer) —

    Direction of a route for which to retrieve bulletins.

  • :stop (String, Integer) —

    Stop along a route for which to retrieve bulletins.

Returns:



190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/cta_redux/bus_tracker.rb', line 190

def self.bulletins!(options={})
  allowed_keys = [:routes, :directions, :stop]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  has_route = options.has_key?(:routes)
  has_stop  = options.has_key?(:stop)

  if !(has_route || has_stop)
    raise "Must provide at least a route or a stop! Try bulletins(:routes => 22)"
  end

  directions = Array.wrap(options[:direction]).flatten.compact.uniq
  routes     = Array.wrap(options[:routes]).flatten.compact.uniq
  stops      = Array.wrap(options[:stop]).flatten.compact.uniq

  if directions.size > 1
    raise "Only one direction may be specified!"
  end

  if directions.any? && routes.size != 1
    raise "Must specify one and only one route when combined with a direction"
  end

  if (directions.any? || routes.any?) && stops.size > 1
    raise "Cannot specify more than one stop when combined with a route and direction"
  end

  routes = routes.join(',')
  stops = stops.join(',')

  connection.get('getservicebulletins', { :rt => routes, :stpid => stops, :dir => directions.first })
end

.cache ⇒ Object

Returns the underlying cache object caching responses (if we’re actually caching responses)

Returns:

  • (Object) 


268
269
270
271
272
273
274
275
 
# File 'lib/cta_redux/bus_tracker.rb', line 268

def self.cache
  if self.cache_responses
    # This is ugly
    @cache || self.connection.builder.handlers.find { |x| x == FaradayMiddleware::Caching }.instance_variable_get(:@args).first
  else
    nil
  end
end

.cache=(cache) ⇒ Object

Note:

Setting the cache object resets the connection. If you’re using the default SimpleCache strategy (built-in 60 second caching), then it will also clear the cache.

Sets the underlying cache object caching responses. Any object can be used that responds to #read, #write, and #fetch

Parameters:

  • cache (Object) 


281
282
283
284
 
# File 'lib/cta_redux/bus_tracker.rb', line 281

def self.cache=(cache)
  @cache = cache
  @connection = nil
end

.cache_responses ⇒ true, false

Returns whether or not cta_redux is caching responses

Returns:

  • (true, false) 


255
256
257
 
# File 'lib/cta_redux/bus_tracker.rb', line 255

def self.cache_responses
  @cache_responses
end

.cache_responses=(should_cache) ⇒ Object

Sets whether or not cta_redux is caching responses

Parameters:

  • should_cache (true, false) 


261
262
263
264
 
# File 'lib/cta_redux/bus_tracker.rb', line 261

def self.cache_responses=(should_cache)
  @cache_responses = should_cache
  @connection = nil
end

.connection ⇒ Object

Returns the connection object we use to talk to the BusTracker API



6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
# File 'lib/cta_redux/bus_tracker.rb', line 6

def self.connection
  raise "You need to set a developer key first. Try CTA::BusTracker.key = 'foo'." unless @key

  @connection ||= Faraday.new do |faraday|
    faraday.url_prefix = 'http://www.ctabustracker.com/bustime/api/v2/'
    faraday.params = { :key => @key }

    faraday.use CTA::BusTracker::Parser, !!@debug
    if @cache_responses
      faraday.response :caching, (@cache || SimpleCache.new(Hash.new))
    end
    faraday.adapter Faraday.default_adapter
  end
end

.debug ⇒ Object

Returns the debug status of the API. When in debug mode, all API responses will additionally return the parsed XML tree, and the original XML for inspection



241
242
243
 
# File 'lib/cta_redux/bus_tracker.rb', line 241

def self.debug
  !!@debug
end

.debug=(debug) ⇒ Object

Sets the debug status of the API. When in debug mode, all API responses will additionally return the parsed XML tree, and the original XML for inspection

Parameters:

  • debug (true, false) 


248
249
250
251
 
# File 'lib/cta_redux/bus_tracker.rb', line 248

def self.debug=(debug)
  @debug = debug
  @connection = nil
end

.directions!(options = {}) ⇒ CTA::BusTracker::DirectionsResponse

Returns the directions in which a route operates (eg Eastbound, Westbound)

Examples:

CTA::BusTracker.directions!(:route => 37)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :route (String, Integer) —

    The route to query for available directions

Returns:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/cta_redux/bus_tracker.rb', line 68

def self.directions!(options={})
  allowed_keys = [:route]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  unless options.has_key?(:route)
    raise "Must specify a route! (Try directions(:route => 914) )"
  end

  routes = Array.wrap(options[:route]).flatten.compact.uniq

  if routes.size > 1
    raise "Only one route may be specified!"
  end
  connection.get('getdirections', { :rt => routes.first })
end

.key ⇒ String

Returns the current API key used to talk to BusTracker

Returns:

  • (String) —

    the api key



227
228
229
 
# File 'lib/cta_redux/bus_tracker.rb', line 227

def self.key
  @key
end

.key=(key) ⇒ Object

Note:

If using SimpleCache as a caching strategy, this resets the cache.

Sets the API key used to talk to BusTracker

Parameters:

  • key (String) —

    The key to use



234
235
236
237
 
# File 'lib/cta_redux/bus_tracker.rb', line 234

def self.key=(key)
  @key = key
  @connection = nil
end

.patterns!(options = {}) ⇒ CTA::BusTracker::PatternsResponse

Returns available patterns for a route

Examples:

CTA::BusTracker.patterns!(:route => 22)
CTA::BusTracker.patterns!(:patterns => [3936, 3932])

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :route (String, Integer) —

    The route to query for patterns. Not available with :patterns

  • :patterns (Array<String>, Array<Integer>, String, Integer) —

    Patterns to return. Not available with :route

Returns:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/cta_redux/bus_tracker.rb', line 127

def self.patterns!(options={})
  allowed_keys = [:route, :patterns]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  has_route   = options.has_key?(:route)
  has_pattern = options.has_key?(:patterns)

  if !(has_pattern || has_route) || (has_pattern && has_route)
    raise "Must specify a pattern OR route option! Try patterns(:route => 37)"
  end

  routes   = Array.wrap(options[:route]).flatten.compact.uniq
  patterns = Array.wrap(options[:patterns]).flatten.compact.uniq.join(',')
  if routes.size > 1
    raise "Only one route may be specified!"
  end

  connection.get('getpatterns', { :pid => patterns, :rt => routes.first })
end

.predictions!(options = {}) ⇒ CTA::BusTracker::PredictionsResponse

Returns a set of arrival/departure predictions.

Examples:

CTA::BusTracker.predictions!(:routes => 22, :stops => 15895)
CTA::BusTracker.predictions!(:vehicles => [2172, 1860], :limit => 1)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :vehicles (Array<String>, Array<Integer>, String, Integer) —

    Vehicles to predict. Not available with :routes

  • :routes (Array<String>, Array<Integer>, String, Integer) —

    Routes to predict. Not available with :vehicles

  • :stops (Array<String>, Array<Integer>, String, Integer) —

    Stops along a route to predict. Required with :routes

  • :limit (String, Integer) —

    Maximum number of predictions to return.

Returns:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/cta_redux/bus_tracker.rb', line 159

def self.predictions!(options={})
  allowed_keys = [:vehicles, :stops, :routes, :limit]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  has_vehicle = options.has_key?(:vehicles)
  has_stop    = options.has_key?(:stops)

  if !(has_stop || has_vehicle) || (has_stop && has_vehicle)
    raise "Must specify a stop (and optionally route), or vehicles! Try predictions(:stops => 6597)"
  end

  routes   = Array.wrap(options[:routes]).flatten.compact.uniq.join(',')
  stops    = Array.wrap(options[:stops]).flatten.compact.uniq.join(',')
  vehicles = Array.wrap(options[:vehicles]).flatten.compact.uniq.join(',')
  limit    = Array.wrap(options[:limit]).first.to_i if options.has_key?(:limit)

  connection.get('getpredictions', { :rt => routes, :vid => vehicles, :stpid => stops, :top => limit })
end

.routes! ⇒ CTA::BusTracker::RoutesResponse

Returns a list of all routes the BusTracker API knows about - whether or not they are active.

Returns:



58
59
60
 
# File 'lib/cta_redux/bus_tracker.rb', line 58

def self.routes!
  connection.get('getroutes')
end

.stops!(options = {}) ⇒ CTA::BusTracker::StopsResponse

Returns the stops along a route and direction

Examples:

CTA::BusTracker.stops!(:route => 22, :direction => :northbound)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :route (String, Integer) —

    The route to query for stops

  • :direction (String, Integer) —

    The direction to query for stops

Returns:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/cta_redux/bus_tracker.rb', line 93

def self.stops!(options={})
  allowed_keys = [:route, :direction]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  has_route     = options.has_key?(:route)
  has_direction = options.has_key?(:direction)

  if !(has_direction && has_route)
    raise "Must specify both direction and route options! Try stops(:route => 37, :direction => :northbound)"
  end

  routes     = Array.wrap(options[:route]).flatten.compact.uniq
  directions = Array.wrap(options[:direction]).flatten.compact.uniq
  if routes.size > 1
    raise "Only one route may be specified!"
  end

  if directions.size > 1
    raise "Only one direction may be specified!"
  end

  connection.get('getstops', { :rt => routes.first, :dir => directions.first.to_s.capitalize })
end

.time! ⇒ CTA::BusTracker::TimeResponse

Returns the current time according to the BusTime servers that power the BusTracker API.

Returns:



23
24
25
 
# File 'lib/cta_redux/bus_tracker.rb', line 23

def self.time!
  connection.get('gettime')
end

.vehicles!(options = {}) ⇒ CTA::BusTracker::VehiclesResponse

Returns status of vehicles out on the road.

Examples:

CTA::BusTracker.vehicles!(:routes => [22,36])
CTA::BusTracker.vehicles!(:vehicles => 4240)

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :vehicles (Array<String>, Array<Integer>, String, Integer) —

    A list or single vehicle IDs to query. Not available with :routes.

  • :routes (Array<String>, Array<Integer>, String, Integer) —

    A list or single route IDs to query. Not available with :vehicles.

Returns:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/cta_redux/bus_tracker.rb', line 37

def self.vehicles!(options={})
  allowed_keys = [:vehicles, :routes]
  if options.keys.any? { |k| !allowed_keys.include?(k) }
    raise "Illegal option!"
  end

  has_vehicle = options.has_key?(:vehicles)
  has_route   = options.has_key?(:routes)

  if !(has_vehicle || has_route) || (has_vehicle && has_route)
    raise "Must specify either vehicle OR route options! Try vehicles(:routes => 37)"
  end

  vehicles = Array.wrap(options[:vehicles]).flatten.compact.uniq.join(',')
  routes   = Array.wrap(options[:routes]).flatten.compact.uniq.join(',')

  connection.get('getvehicles', { :rt => routes, :vid => vehicles })
end