Class: Craigslist::API::PostingStats

Inherits:
Object
  • Object
show all
Defined in:
lib/craigslist/api/posting_stats.rb

Overview

Daily engagement counts for a posting.

Craigslist reports each metric as [unix_timestamp, count] pairs, one per UTC day, over a rolling thirty-day window ending at midnight UTC yesterday. Counts are requests, not unique viewers.

Constant Summary collapse

METRICS =

Every metric the API reports.

%i[
  impressions
  views
  contact
  contact_chat
  contact_phone
  contact_email
  share
  favorite
].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(posting_id: nil, series: {}) ⇒ PostingStats

Returns a new instance of PostingStats.



30
31
32
33
34
 
# File 'lib/craigslist/api/posting_stats.rb', line 30

def initialize(posting_id: nil, series: {})
  @posting_id = posting_id
  @series = series.freeze
  freeze
end

Instance Attribute Details

#posting_id ⇒ String? (readonly)

Returns absent when the stats were requested for a single posting, since the id is then already known.

Returns:

  • (String, nil) —

    absent when the stats were requested for a single posting, since the id is then already known



25
26
27
 
# File 'lib/craigslist/api/posting_stats.rb', line 25

def posting_id
  @posting_id
end

#series ⇒ Hash{Symbol => Array<Array(Time, Integer)>} (readonly)

Returns:

  • (Hash{Symbol => Array<Array(Time, Integer)>}) 


28
29
30
 
# File 'lib/craigslist/api/posting_stats.rb', line 28

def series
  @series
end

Class Method Details

.from(hash) ⇒ PostingStats

Parameters:

  • hash (Hash) —

    raw payload for one posting

Returns:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
 
# File 'lib/craigslist/api/posting_stats.rb', line 38

def self.from(hash)
  hash ||= {}

  series = METRICS.each_with_object({}) do |metric, memo|
    points = hash[metric.to_s]
    next if points.nil?

    memo[metric] = Array(points).map do |(timestamp, count)|
      [Time.at(timestamp.to_i).utc, count.to_i]
    end
  end

  new(posting_id: hash["postingId"], series: series)
end

Instance Method Details

#[](metric) ⇒ Array<Array(Time, Integer)>

Time series for one metric.

Parameters:

  • metric (Symbol) —

    one of METRICS

Returns:

  • (Array<Array(Time, Integer)>) —

    empty when not reported



57
58
59
 
# File 'lib/craigslist/api/posting_stats.rb', line 57

def [](metric)
  series.fetch(metric.to_sym, [])
end

#inspect ⇒ Object 



79
80
81
82
 
# File 'lib/craigslist/api/posting_stats.rb', line 79

def inspect
  "#<#{self.class.name} posting_id=#{posting_id.inspect} " \
    "metrics=#{reported_metrics.inspect}>"
end

#reported_metrics ⇒ Array<Symbol>

Returns metrics that carry data.

Returns:

  • (Array<Symbol>) —

    metrics that carry data



75
76
77
 
# File 'lib/craigslist/api/posting_stats.rb', line 75

def reported_metrics
  series.keys
end

#total(metric) ⇒ Integer

Sum of a metric across the whole window.

Parameters:

  • metric (Symbol) —

    one of METRICS

Returns:

  • (Integer) 


65
66
67
 
# File 'lib/craigslist/api/posting_stats.rb', line 65

def total(metric)
  self[metric].sum { |(_, count)| count }
end