Getting started for Python developers

Directed Edge makes integrating with our recommendations engine easy with Python. We provide bindings that handle all of the communication with our server transparently using normal Python 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 Python bindings from GitHub and copy the file named Python/directed_edge.py into your project. You'll need to make sure you have urllib, urllib2 and httplib2 installed. We used easy_install to grab them.

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.

Tags

Items also have tags, so John Doe would probably have a user tag and Blonde on Blonde would have a product tag. Tags don't weigh into the ranking at all — they're just used so that you can filter the sort of results you'd like to get. So if you want to show related products, you'd run a query looking for things with the tag 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.

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.

Note: You will need to change the usernames / passwords in the ExampleStore constructor.

Comments will follow, but the flow is identical to the Ruby Bindings for E-Commerce Tutorial.

#!/usr/bin/python

from sqlalchemy import Column, Integer, create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

from directed_edge import Exporter, Item, Database

Base = declarative_base()

class Customer(Base):
    __tablename__ = "customers"
    id = Column(Integer, primary_key=True)

class Product(Base):
    __tablename__ = "products"
    id = Column(Integer, primary_key=True)

class Purchase(Base):
    __tablename__ = "purchases"
    customer = Column(Integer, primary_key=True)
    product = Column(Integer, primary_key=True)

class ExampleStore(object):
    def __init__(self):
        self.database = Database("examplestore", "password")
        engine = create_engine("mysql://examplestore:password@localhost/examplestore")
        Session = sessionmaker(bind=engine)
        self.session = Session()

    def export_from_mysql(self):
        exporter = Exporter("examplestore.xml")

        for product in self.session.query(Product):
            item = Item(exporter.database, "product%s" % product.id)
            item.add_tag("product")
            exporter.export(item)
            
        for customer in self.session.query(Customer):
            item = Item(exporter.database, "customer%s" % customer.id)
            item.add_tag("customer")
            for purchase in self.session.query(Purchase).filter_by(customer=customer.id):
                item.link_to("product%s" % purchase.product)
            exporter.export(item)

        exporter.finish()

    def import_to_directededge(self):
        self.database.import_from_file("examplestore.xml")

    def create_customer(self, id):
        item = Item(self.database, "customer%s" % id)
        item.add_tag("customer")
        item.save()

    def create_product(self, id):
        item = Item(self.database, "product%s" % id)
        item.add_tag("product")
        item.save()

    def add_purchase(self, customer_id, product_id):
        item = Item(self.database, "customer%s" % customer_id)
        item.link_to("product%s" % product_id)
        item.save()

    def related_products(self, product_id):
        item = Item(self.database, "product%s" % product_id)
        return [related.replace("product", "") for related in item.related(["product"])]

    def personalized_recommendations(self, customer_id):
        item = Item(self.database, "customer%s" % customer_id)
        return [related.replace("product", "") for related in item.recommended(["product"])]
        
store = ExampleStore()
store.export_from_mysql()
store.import_to_directededge()

store.create_customer(1000)
store.create_product(1000)
store.add_purchase(1000, 1000)

print store.related_products(2)
print store.personalized_recommendations(2)

Further Reading

If you want to dig deeper into how the web services work — the REST API, XML Format and Web Services Examples articles explain what's going on behind the scenes when you use our bindings.