Directed Edge - Developer Base

Directed Edge makes integrating with our recommendations engine easy with Ruby. We provide bindings that handle all of the communication with our server transparently using normal Ruby objects.

Getting started

Introduction to Recommendations is a good starting point if you're wondering how recommendations work or what they're useful for.
API Concepts explains some of the basics of hour our API works and introduces the concepts of items, tags and links, also explained briefly below.
Grab the Ruby bindings from GitHub and copy the file named Ruby/directed_edge.rb into your project. You'll need to make sure you have rubygems and the rest_client Gem installed. Alternatively, you can install our Gem directly with sudo gem install directed-edge.

Data modeling

Items and links

To model the data from your site, you'll need to figure out what your items are. Usually they're things like users, products and articles. We represent a relationship between items by links. So, if you have Bob Dylan's "Blonde on Blonde" that you want to say was bought by "John Doe", you create a link from "John Doe" to "Blonde on Blonde".

Identifiers

Usually we don't need to actually know the names of those items — they just need a unique identifier. Typically that's something like customer1 and product1. Most people just use the ID field from their own database. So if you have a MySQL table named products and Blonde on Blonde is at the row with ID 42 then you'd just use product42 as your identifier for that product.

Querying for recommendations

We offer two primary sorts of recommendations, called related and recommended:

Related is for example if you have one product and you want to find similar products, or a user and want to find similar users. To find products related to Blonde on Blonde you'd send a related query for that item, looking for things tagged product.

Recommended is for doing personalized recommendations, e.g. Products Bob is likely to be interested in... To do a recommended query, you would send a request for the item that corresponds to Bob looking for things that are tagged product.

API Documentation

You can find full documentation for the bindings classes here.

Tutorial

Ruby Bindings for E-Commerce Tutorial provides a detailed step-by-step walkthrough of how to get up and going with a store — it's based on the same code as below, but with lots of details.

Example

ExampleStore is an example of how you'd connect a store with customers, products and purchases to our recommendations engine, including exporting data and querying the web services.

#!/usr/bin/ruby
 
require 'rubygems'
require 'activerecord'
require 'directed_edge'
 
ActiveRecord::Base.establish_connection(:adapter => 'mysql',
                                        :host => 'localhost',
                                        :username => 'examplestore',
                                        :password => 'password',
                                        :database => 'examplestore')
 
class Customer < ActiveRecord::Base
end
 
class Product < ActiveRecord::Base
end
 
class Purchase < ActiveRecord::Base
end
 
class ExampleStore
  def initialize
    @database = DirectedEdge::Database.new('examplestore', 'password')
  end
 
  def export_from_mysql
    exporter = DirectedEdge::Exporter.new('examplestore.xml')
 
    Customer.find(:all).each do |customer|
      item = DirectedEdge::Item.new(exporter.database, "customer#{customer.id}")
      item.add_tag('customer')
      purchases = Purchase.find(:all, :conditions => { :customer => customer.id })
      purchases.each { |purchase| item.link_to("product#{purchase.product}") }
      exporter.export(item)
    end
 
    Product.find(:all).each do |product|
      item = DirectedEdge::Item.new(exporter.database, "product#{product.id}")
      item.add_tag('product')
      exporter.export(item)
    end
 
    exporter.finish
  end
 
  def import_to_directededge
    @database.import('examplestore.xml')
  end
 
  def create_customer(id)
    item = DirectedEdge::Item.new(@database, "customer#{id}")
    item.add_tag('customer')
    item.save
  end
 
  def create_product(id)
    item = DirectedEdge::Item.new(@database, "product#{id}")
    item.add_tag('product')
    item.save
  end
 
  def add_purchase(customer_id, product_id)
    item = DirectedEdge::Item.new(@database, "customer#{customer_id}")
    item.link_to("product#{product_id}")
    item.save
  end
 
  def related_products(product_id)
    item = DirectedEdge::Item.new(@database, "product#{product_id}")
    item.related(['product']).map { |product| product.sub('product', '').to_i }
  end
 
  def personalized_recommendations(customer_id)
    item = DirectedEdge::Item.new(@database, "customer#{customer_id}")
    item.recommended(['product']).map { |product| product.sub('product', '').to_i }
  end
end
 
store = ExampleStore.new
 
store.export_from_mysql
store.import_to_directededge
 
store.create_customer(500)
store.create_product(2000)
store.add_purchase(500, 2000)
 
store.related_products(1).each do |product|
  puts "Related products for product 1: #{product}"
end
 
store.personalized_recommendations(1).each do |product|
  puts "Personalized recommendations for user 1: #{product}"
end

Contents