Buzz

Ruby client for the Buzz/Freewheel Advertiser API v2.

Installation

Requires Ruby 3.0+.

Add to your Gemfile:

gem "buzzrb"

Or install directly:

gem install buzzrb

Quickstart

require "buzz"

Buzz.configure do |c|
  c.buzz_key  = "my-buzz-key"
  c.email     = "user@example.com"
  c.password  = "secret"
end

client = Buzz::Client.new
campaigns = client.campaigns.list.to_a

Authentication happens automatically on the first request. You can also pass credentials directly:

client = Buzz::Client.new(
  buzz_key: "my-buzz-key",
  email:    "user@example.com",
  password: "secret"
)

Features

CRUD Operations

Every resource (advertisers, campaigns, line_items, creatives, creative_templates, segments, targeting, creative_assets) supports the same interface:

# Create
campaign = client.campaigns.create(
  advertiser_id: 1,
  name: "Summer 2026"
)

# Read
campaign = client.campaigns.find(42)

# Update
client.campaigns.update(42, name: "Fall 2026")

# Delete
client.campaigns.delete(42)

Pagination

list returns an Enumerable paginator that follows next-page links automatically:

# Iterate through all results
client.line_items.list(advertiser_id: 1).each do |item|
  puts item["line_item_name"]
end

# Or page by page
client.line_items.list.each_page do |page|
  puts "Got #{page.results.size} results"
end

Reporting

Report Builder 2.0 queries are asynchronous. query POSTs /rest/v2/reporting/run-query, then polls /rest/v2/reporting/async-results/{task_id} (204 while running, 200 when done):

rows = client.reporting.query(
  view: "performance_agg",
  fields: ["bid_day", "advertiser_id", "line_item_id", "spend"],
  filters: { bid_day: "yesterday" },
  result_format: "json",
  query_timezone: "America/New_York"
)
rows.each { |r| puts "#{r['advertiser_id']}: $#{r['spend']}" }

List available report views and fields:

client.reporting.reports
client.reporting.report("performance_agg")

Search

results = client.search(query: "acme", types: [:campaign, :line_item])

Error Handling

All API errors raise typed exceptions under Buzz::Error:

begin
  client.campaigns.find(999)
rescue Buzz::NotFoundError => e
  puts e.message
  puts e.status  # => 404
rescue Buzz::RateLimitError => e
  sleep e.retry_after
  retry
rescue Buzz::ValidationError, Buzz::AuthenticationError, Buzz::ServerError => e
  puts "#{e.class}: #{e.message}"
end

Configuration Options

Option	Default	Description
`buzz_key`	—	Your Buzz buzz key (required)
`email`	—	Account email (required)
`password`	—	Account password (required)
`account_id`	`nil`	Scope authentication to a specific account
`timezone`	`nil`	Sent as `X-Timezone` header
`keep_logged_in`	`true`	Call keep-logged-in after authenticating
`base_url`	`https://{buzz_key}.api.beeswax.com`	Override the API base URL
`open_timeout`	`10`	Connection open timeout in seconds
`read_timeout`	`30`	Read timeout in seconds

Testing

bundle exec rake test

License

MIT

buzzrb

Development