https://developer.directededge.com/api.php?action=feedcontributions&user=Scott&feedformat=atomthe Directed Edge Developer Base - User contributions [en]2024-03-29T14:41:47ZUser contributionsMediaWiki 1.28.2https://developer.directededge.com/index.php?title=Shopify_Liquid&diff=342Shopify Liquid2018-07-12T12:32:18Z<p>Scott: </p>
<hr />
<div>See also our page with [[Shopify Liquid Examples]].<br />
<br />
== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in our [http://shopify.directededge.com/settings#styling Appearance Settings].<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}<br />
<br />
<br />
=== <tt>product</tt> ===<br />
<br />
We support the same variables as Shopify, with the following additions. See their documentation for <tt>[http://docs.shopify.com/themes/liquid-variables/product product]</tt>.<br />
<br />
{| class="variable-ref-table"<br />
| buy_link || A link that will add the product to the shopping cart and will ask the user to pick a variant if multiple variants are available for the product.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=341REST API2014-07-03T20:16:40Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
'''Warning''': This clears all data from the database and resets it to its default empty condition. Use with caution.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating items (potentially incrementally). The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace the item.<br />
* '''add''': This means that the posted content should be added to the already existing content.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
==== ''type''Weight ====<br />
<br />
If you've used different [[XML Format#type attribute|link types]] in your data, you can specify different link weights for the different link types in the query. For example, if you used the type ''viewed'' and ''linked'' you could do:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|viewedWeight&#61;5&amp;linkedWeight&#61;10}}</tt><br />
<br />
Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).<br />
<br />
Also note that once you have specified one or more ''type''Weights, only those types which have been assigned a weight will be included in the computations.<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=340Recommendation parameters2014-07-03T20:15:20Z<p>Scott: </p>
<hr />
<div>''List'' parameters are just a comma separated list of strings, defaulting to an empty list.<br />
<br />
{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| float<br />
| ''type''Weight<br />
| <br />
| Specifies the relative weights of various link types. See [[REST API#typeWeight|the description in our REST docs]]<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ add, subtract, replace ]<br />
| updateMethod<br />
| replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=339Shopify Liquid Examples2014-03-27T09:57:47Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Note that in general you'll probably want to incorporate the CSS that's here into your site's main CSS file(s), but it's included here to make the examples more complete and usable out of the box.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Basic Example (Plain-text output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
</div><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Default ==<br />
<br />
This is a simple, but usable style that's shown by default when you switch to the custom layout mode. It features a simple list of up to 5 products per recommendations type, plus bundles. Products are shown with a simple 5 pixel border. This is a responsive style.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first"<br />
src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last"<br />
src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
</div><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<div class="recommendations-product"><br />
<div class="recommendations-product-image"><br />
<a href="{{ product.url }}"><br />
<img src="{{ product.featured_image | product_img_url: 'compact' }}"><br />
</a><br />
</div><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
<br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
clear: both;<br />
}<br />
.recommendations-group .recommendations-product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .recommendations-product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .recommendations-product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
.recommendations-product-image {<br />
position: relative;<br />
bottom: 0px;<br />
height: 180px;<br />
}<br />
.recommendations-product-image img {<br />
position: absolute;<br />
bottom: 0px;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
margin-bottom: 1em;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em;<br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em;<br />
}<br />
</style><br />
</source><br />
</div><br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div></div>Scotthttps://developer.directededge.com/index.php?title=XML_Format&diff=338XML Format2014-03-07T11:16:22Z<p>Scott: </p>
<hr />
<div>So, keeping in mind all of the basic structures from [[API Concepts]], let's see what they look like in XML.<br />
<br />
There are three major cases in which we'll get or send XML to the Directed Edge [[REST API]]:<br />
<br />
* '''Import / Export''' - this is just a list of all items with all of their links, properties and tags included.<br />
* '''Updates''' - you can update single items in the database or add or remove links, properties and tags.<br />
* '''Queries''' - for ''related'' or ''recommended'' items (there's a difference).<br />
<br />
The first two basically have the same form, with the notable difference that imports and exports contain multiple items, whereas updates only contain one item. Queries contain a list of item identifiers that are related to the query item.<br />
<br />
== Import / export example ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
<item id='product_1'><br />
<tag>product</tag><br />
<property name='artist'>Beatles</property><br />
<property name='name'>White Album</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Here we've got a customer, named ''Bob Schmidt'' that's connected to an album called ''The White Album'' by ''Beatles''. So we've got two [[item]]s and one [[link]]. Let's start breaking this down a little.<br />
<br />
If you imported this to your Directed Edge account using the [[REST API]], you'd have a database with two items. Similarly, if you requested a database export right after that, this is what you'd get back.<br />
<br />
'''Before you start sending XML to our server, we recommend passing it through [http://www.xmlsoft.org/xmllint.html xmllint] or similar to make sure that the XML is valid.''' The most common problem that we see with users that are new to the API is sending invalid XML and then our servers choking on it.<br />
<br />
== Related / recommended query example ==<br />
<br />
: ''Results for things related to "Web 2.0" in our Wikipedia database''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="Web 2.0"><br />
<related>Ajax (programming)</related><br />
<related>Delicious (website)</related><br />
<related>Flickr</related><br />
<related>Web service</related><br />
<related>RSS</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
The result structure here is pretty self-explanatory &mdash; the item is the one which was queried for and the list of results contains the identifiers of the related items. Here, notably, the order is important. Items near the top of the list rank higher than items further down.<br />
<br />
The only difference in the XML between an ''related'' and ''recommended'' query is the name of the element that the results are wrapped in.<br />
<br />
== Update examples ==<br />
<br />
: ''Do a complete update on the item user_1''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is the same format as we used for an import except that there's only one item. As noted in the [[REST API]] if this is PUT to an item it will overwrite all existing data.<br />
<br />
: ''Add or remove the tag "user" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>user</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is basically just a snippet from a usual item. One notable difference is that the item id may (but doesn't have to be) omitted for updating an item (using the add or remove methods noted in the API docs).<br />
<br />
: ''Remove the property "last name" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<property name="last name"></property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Similar to adding a tag, when removing a property it's worth noting that the value of the property is completely ignored.<br />
<br />
== XML header ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
</source><br />
<br />
Good old garden variety [[Wikipedia:XML|XML]] header. We prefer UTF-8, but we shouldn't blow up if you send us other stuff.<br />
<br />
== directededge element ==<br />
<br />
<source lang="xml"><br />
<directededge version="0.1"><br />
</source><br />
<br />
Nothing too exotic here for the moment. This wraps up all of the stuff that you'll send our receive for the moment. Version is always ''0.1'' for the moment because, well, we're too lazy to bump the version. (Though we'll do better versioning once we're out of beta.)<br />
<br />
== item element ==<br />
<br />
<source lang="xml"><br />
<item id='user_1'><br />
</source><br />
<br />
An item is the container for all of the stuff in our database. Exactly what items are is explained in [[API Concepts]].<br />
<br />
=== id attribute ===<br />
<br />
Every item ''must'' have an id attribute. That's the handle that we use to refer to the item everywhere. If you want to update or delete the item, you refer to it by its ''id''. You can use any scheme that you want to for creating item identifiers, so long as they're unique. Often something like ''type''_''number'' is convenient.<br />
<br />
== tag element ==<br />
<br />
Tags are always a child element of an ''item''. Tags can be free form as well. Usually they're things like ''user'', ''product'', ''page'', but they can also be much more specific like, ''artist'', ''album'', ''sci-fi'', etc. You can associate as many tags as you would like with a particular item.<br />
<br />
== property element ==<br />
<br />
<source lang="xml"><br />
<property name='last name'>Schmidt</property><br />
</source><br />
<br />
Properties are a set of key-value pairs associate with an item. Again, they are free form. You don't need to insert all of the values that you store locally in your database, in fact, most of the time you don't need to associate any at all. These are only useful if you later would like to grab data from the Directed Edge [[REST API]] about the items that you're storing there. You can associate as many properties with an item as you like, so long as their names are unique.<br />
<br />
=== name attribute ===<br />
<br />
Every property ''must'' have a name attribute. This can be anything that you like, but there may only be one property with a given name per item.<br />
<br />
== link element ==<br />
<br />
<source lang="xml"><br />
<link>product_1</link><br />
<link weight="3">product_2</link><br />
<link type="purchase">product_3</link><br />
</source><br />
<br />
The link element, surprise, surprise &mdash; indicates a link between two items. The identifiers used in the text, here ''product_1'', ''product_2'', and ''product_3'' are just the IDs of items in the database.<br />
<br />
'''Links to items that do not exist will be ignored unless those items are defined in the same import.''' In other words, if you have a link to an item that's defined lower in the same batch of XML, no problemo. But if you create a dead link, that just gets ignored.<br />
<br />
=== weight attribute ===<br />
<br />
The weight attribute is what we use for stuff like rankings. Weights can be in the range of 1 to 10 (or zero if you want to explicitly say there's no weight).<br />
<br />
So, if we want to say ''user_1 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== type attribute ===<br />
<br />
This specifies a type for the link. ''Link types'' can be imagined as a set of graphs superimposed upon each other. For example, in an e-commerce settings, these could be ''purchased'', ''rated'', ''category'', etc.<br />
<br />
You can then mix and match these ''types'' in recommendations &mdash; for example if you wanted to show related products based mostly on purchase, but also considering category information, you can specify that at query time. See our [[REST API]] for details on how to query link types.<br />
<br />
So, if we want to say ''user_1 purchaseds product_1 and product_2 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link type="purchase">product_1</link><br />
<link type="purchase">product_2</link><br />
<link type="rating" weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== ''weights'' vs. ''types'' ===<br />
<br />
There is both a semantic and practical different between weights and types.<br />
<br />
* '''Weights''' are used to represent things that are intrinsic to the data, but where the links being related are categorically similar. Ratings would be one notable example, repeat purchases would be another.<br />
<br />
* '''Types''' are used to specify different categories of relationships. For things that are categorically different, types have the advantage that they may be mixed and matched at query time rather than needing to be encoded, as with weights, at the time the data is uploaded to our service.<br />
<br />
== preselected element ==<br />
<br />
This is a simple way to specify that another item should always appear in the recommendations returned for this item.<br />
<br />
<source lang="xml"><br />
<preselected>product_1</preselected><br />
</source><br />
<br />
== blacklisted element ==<br />
<br />
This is a simple way to specify that another item should never appear in the recommendations returned for this item.<br />
<br />
<source lang="xml"><br />
<blacklisted>product_1</blacklisted><br />
</source><br />
<br />
== related element ==<br />
<br />
<source lang="xml"><br />
<related>user_1</related><br />
</source><br />
<br />
Totally no frills. Results from a ''related'' items query. Order matters.<br />
<br />
== recommended element ==<br />
<br />
<source lang="xml"><br />
<recommended>product_1</recommended><br />
</source><br />
<br />
Same deal as the related element, but for the results of ''recommended'' queries.<br />
<br />
== See also ==<br />
<br />
* [[Web Services Examples]]</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=337REST API2014-02-21T13:03:50Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
'''Warning''': This clears all data from the database and resets it to its default empty condition. Use with caution.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating items (potentially incrementally). The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace the item.<br />
* '''add''': This means that the posted content should be added to the already existing content.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
==== ''type''Weight ====<br />
<br />
If you've used different [[XML Format#type attribute|link types]] in your data, you can specify different link weights for the different link types in the query. For example, if you used the type ''viewed'' and ''linked'' you could do:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|viewedWeight&#61;5&amp;linkedWeight&#61;10}}</tt><br />
<br />
Of note here is that weights for items with an unspecified link type can be specified with <tt>defaultWeight=1</tt> (where 1 can be substituted for the appropriate weight).<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=336REST API2014-02-21T11:59:18Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
'''Warning''': This clears all data from the database and resets it to its default empty condition. Use with caution.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating items (potentially incrementally). The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace the item.<br />
* '''add''': This means that the posted content should be added to the already existing content.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=335REST API2014-02-21T11:58:20Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating items (potentially incrementally). The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace the item.<br />
* '''add''': This means that the posted content should be added to the already existing content.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt><br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=334REST API2014-02-21T11:57:50Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating items (potentially incrementally). The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace the item.<br />
* '''add''': This means that the posted content should be added to the already existing content.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that any values that are specified will be removed (e.g. to remove a tag) from the items present in the post.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis?|updateMethod&#61;subtract}}</tt><br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=333REST API2014-02-21T11:51:57Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
These would be, respectively:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;replace}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia?|updateMethod&#61;subtract}}</tt><br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=332REST API2014-02-21T11:42:35Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=331REST API2014-02-21T11:42:01Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=330REST API2014-02-21T11:40:15Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
<br />
=== HTTP POST ===<br />
<br />
This is used for updating the database in batch. The key [[Recommendation parameters|query parameter]] is '''updateMethod'''. Valid values are:<br />
<br />
* '''replace''': This is the default. This means that the posted content should replace everything in the database.<br />
* '''add''': This means that the posted content should be added to the already existing content in the database.<br />
* '''subtract''': This means that the values should be ''subtracted'' from the database. In this case, subtraction means that for an individual item, any values that are specified will be removed (e.g. to remove a tag) from the items present in the post. If an item does not contain any additional tags in this data, then the item itself will be removed.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=329Recommendation parameters2014-02-21T06:32:58Z<p>Scott: </p>
<hr />
<div>''List'' parameters are just a comma separated list of strings, defaulting to an empty list.<br />
<br />
{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ add, subtract, replace ]<br />
| updateMethod<br />
| replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=328REST API2014-02-21T05:53:13Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=327Recommendation parameters2014-02-21T05:49:55Z<p>Scott: </p>
<hr />
<div>''List'' parameters are just a comma separated list of strings, defaulting to an empty list.<br />
<br />
{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ add, subtract, replace ]<br />
| updateMethod<br />
| Replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=326REST API2014-02-21T04:26:55Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== Add sub-resource ===<br />
<br />
You can incrementally do batch updates to the database by appending ''add'' to the end of the URL. The XML format is the same as for a normal import, but it will not first clear the database the items in the database will be the combination of previously existing data, plus the new data. Specifically, if you already had an item with some links and tags and wanted to add another tag, you would enter that item with no data other than the new tag and the result would be an item with those properties and links, plus the new tag.<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/|add|}}</tt><br />
<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[[Recommendation parameters]]'''</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=325REST API2014-02-21T04:26:39Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== Add sub-resource ===<br />
<br />
You can incrementally do batch updates to the database by appending ''add'' to the end of the URL. The XML format is the same as for a normal import, but it will not first clear the database the items in the database will be the combination of previously existing data, plus the new data. Specifically, if you already had an item with some links and tags and wanted to add another tag, you would enter that item with no data other than the new tag and the result would be an item with those properties and links, plus the new tag.<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/|add|}}</tt><br />
<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.<br />
<br />
<br />
==== Additional query options ====<br />
<br />
The above are the most common query parameters. Our full list of supported query parameters, which have similar usage as the options above, is here:<br />
<br />
* '''[Recommendation parameters]'''</div>Scotthttps://developer.directededge.com/index.php?title=XML_Format&diff=324XML Format2014-02-21T04:14:17Z<p>Scott: </p>
<hr />
<div>So, keeping in mind all of the basic structures from [[API Concepts]], let's see what they look like in XML.<br />
<br />
There are three major cases in which we'll get or send XML to the Directed Edge [[REST API]]:<br />
<br />
* '''Import / Export''' - this is just a list of all items with all of their links, properties and tags included.<br />
* '''Updates''' - you can update single items in the database or add or remove links, properties and tags.<br />
* '''Queries''' - for ''related'' or ''recommended'' items (there's a difference).<br />
<br />
The first two basically have the same form, with the notable difference that imports and exports contain multiple items, whereas updates only contain one item. Queries contain a list of item identifiers that are related to the query item.<br />
<br />
== Import / export example ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
<item id='product_1'><br />
<tag>product</tag><br />
<property name='artist'>Beatles</property><br />
<property name='name'>White Album</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Here we've got a customer, named ''Bob Schmidt'' that's connected to an album called ''The White Album'' by ''Beatles''. So we've got two [[item]]s and one [[link]]. Let's start breaking this down a little.<br />
<br />
If you imported this to your Directed Edge account using the [[REST API]], you'd have a database with two items. Similarly, if you requested a database export right after that, this is what you'd get back.<br />
<br />
'''Before you start sending XML to our server, we recommend passing it through [http://www.xmlsoft.org/xmllint.html xmllint] or similar to make sure that the XML is valid.''' The most common problem that we see with users that are new to the API is sending invalid XML and then our servers choking on it.<br />
<br />
== Related / recommended query example ==<br />
<br />
: ''Results for things related to "Web 2.0" in our Wikipedia database''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="Web 2.0"><br />
<related>Ajax (programming)</related><br />
<related>Delicious (website)</related><br />
<related>Flickr</related><br />
<related>Web service</related><br />
<related>RSS</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
The result structure here is pretty self-explanatory &mdash; the item is the one which was queried for and the list of results contains the identifiers of the related items. Here, notably, the order is important. Items near the top of the list rank higher than items further down.<br />
<br />
The only difference in the XML between an ''related'' and ''recommended'' query is the name of the element that the results are wrapped in.<br />
<br />
== Update examples ==<br />
<br />
: ''Do a complete update on the item user_1''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is the same format as we used for an import except that there's only one item. As noted in the [[REST API]] if this is PUT to an item it will overwrite all existing data.<br />
<br />
: ''Add or remove the tag "user" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>user</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is basically just a snippet from a usual item. One notable difference is that the item id may (but doesn't have to be) omitted for updating an item (using the add or remove methods noted in the API docs).<br />
<br />
: ''Remove the property "last name" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<property name="last name"></property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Similar to adding a tag, when removing a property it's worth noting that the value of the property is completely ignored.<br />
<br />
== XML header ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
</source><br />
<br />
Good old garden variety [[Wikipedia:XML|XML]] header. We prefer UTF-8, but we shouldn't blow up if you send us other stuff.<br />
<br />
== directededge element ==<br />
<br />
<source lang="xml"><br />
<directededge version="0.1"><br />
</source><br />
<br />
Nothing too exotic here for the moment. This wraps up all of the stuff that you'll send our receive for the moment. Version is always ''0.1'' for the moment because, well, we're too lazy to bump the version. (Though we'll do better versioning once we're out of beta.)<br />
<br />
== item element ==<br />
<br />
<source lang="xml"><br />
<item id='user_1'><br />
</source><br />
<br />
An item is the container for all of the stuff in our database. Exactly what items are is explained in [[API Concepts]].<br />
<br />
=== id attribute ===<br />
<br />
Every item ''must'' have an id attribute. That's the handle that we use to refer to the item everywhere. If you want to update or delete the item, you refer to it by its ''id''. You can use any scheme that you want to for creating item identifiers, so long as they're unique. Often something like ''type''_''number'' is convenient.<br />
<br />
== tag element ==<br />
<br />
Tags are always a child element of an ''item''. Tags can be free form as well. Usually they're things like ''user'', ''product'', ''page'', but they can also be much more specific like, ''artist'', ''album'', ''sci-fi'', etc. You can associate as many tags as you would like with a particular item.<br />
<br />
== property element ==<br />
<br />
<source lang="xml"><br />
<property name='last name'>Schmidt</property><br />
</source><br />
<br />
Properties are a set of key-value pairs associate with an item. Again, they are free form. You don't need to insert all of the values that you store locally in your database, in fact, most of the time you don't need to associate any at all. These are only useful if you later would like to grab data from the Directed Edge [[REST API]] about the items that you're storing there. You can associate as many properties with an item as you like, so long as their names are unique.<br />
<br />
=== name attribute ===<br />
<br />
Every property ''must'' have a name attribute. This can be anything that you like, but there may only be one property with a given name per item.<br />
<br />
== link element ==<br />
<br />
<source lang="xml"><br />
<link>product_1</link><br />
<link weight="3">product_2</link><br />
<link type="purchase">product_3</link><br />
</source><br />
<br />
The link element, surprise, surprise &mdash; indicates a link between two items. The identifiers used in the text, here ''product_1'', ''product_2'', and ''product_3'' are just the IDs of items in the database.<br />
<br />
'''Links to items that do not exist will be ignored unless those items are defined in the same import.''' In other words, if you have a link to an item that's defined lower in the same batch of XML, no problemo. But if you create a dead link, that just gets ignored.<br />
<br />
=== weight attribute ===<br />
<br />
The weight attribute is what we use for stuff like rankings. Weights can be in the range of 1 to 10 (or zero if you want to explicitly say there's no weight).<br />
<br />
So, if we want to say ''user_1 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== type attribute ===<br />
<br />
This specifies a type for the link. ''Link types'' can be imagined as a set of graphs superimposed upon each other. For example, in an e-commerce settings, these could be ''purchased'', ''rated'', ''category'', etc.<br />
<br />
You can then mix and match these ''types'' in recommendations &mdash; for example if you wanted to show related products based mostly on purchase, but also considering category information, you can specify that at query time. See our [[REST API]] for details on how to query link types.<br />
<br />
So, if we want to say ''user_1 purchaseds product_1 and product_2 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link type="purchase">product_1</link><br />
<link type="purchase">product_2</link><br />
<link type="rating" weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== ''weights'' vs. ''types'' ===<br />
<br />
There is both a semantic and practical different between weights and types.<br />
<br />
* '''Weights''' are used to represent things that are intrinsic to the data, but where the links being related are categorically similar. Ratings would be one notable example, repeat purchases would be another.<br />
<br />
* '''Types''' are used to specify different categories of relationships. For things that are categorically different, types have the advantage that they may be mixed and matched at query time rather than needing to be encoded, as with weights, at the time the data is uploaded to our service.<br />
<br />
== related element ==<br />
<br />
<source lang="xml"><br />
<related>user_1</related><br />
</source><br />
<br />
Totally no frills. Results from a ''related'' items query. Order matters.<br />
<br />
== recommended element ==<br />
<br />
<source lang="xml"><br />
<recommended>product_1</recommended><br />
</source><br />
<br />
Same deal as the related element, but for the results of ''recommended'' queries.<br />
<br />
== See also ==<br />
<br />
* [[Web Services Examples]]</div>Scotthttps://developer.directededge.com/index.php?title=XML_Format&diff=323XML Format2014-02-21T04:14:00Z<p>Scott: </p>
<hr />
<div>So, keeping in mind all of the basic structures from [[API Concepts]], let's see what they look like in XML.<br />
<br />
There are three major cases in which we'll get or send XML to the Directed Edge [[REST API]]:<br />
<br />
* '''Import / Export''' - this is just a list of all items with all of their links, properties and tags included.<br />
* '''Updates''' - you can update single items in the database or add or remove links, properties and tags.<br />
* '''Queries''' - for ''related'' or ''recommended'' items (there's a difference).<br />
<br />
The first two basically have the same form, with the notable difference that imports and exports contain multiple items, whereas updates only contain one item. Queries contain a list of item identifiers that are related to the query item.<br />
<br />
== Import / export example ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
<item id='product_1'><br />
<tag>product</tag><br />
<property name='artist'>Beatles</property><br />
<property name='name'>White Album</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Here we've got a customer, named ''Bob Schmidt'' that's connected to an album called ''The White Album'' by ''Beatles''. So we've got two [[item]]s and one [[link]]. Let's start breaking this down a little.<br />
<br />
If you imported this to your Directed Edge account using the [[REST API]], you'd have a database with two items. Similarly, if you requested a database export right after that, this is what you'd get back.<br />
<br />
'''Before you start sending XML to our server, we recommend passing it through [http://www.xmlsoft.org/xmllint.html xmllint] or similar to make sure that the XML is valid.''' The most common problem that we see with users that are new to the API is sending invalid XML and then our servers choking on it.<br />
<br />
== Related / recommended query example ==<br />
<br />
: ''Results for things related to "Web 2.0" in our Wikipedia database''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="Web 2.0"><br />
<related>Ajax (programming)</related><br />
<related>Delicious (website)</related><br />
<related>Flickr</related><br />
<related>Web service</related><br />
<related>RSS</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
The result structure here is pretty self-explanatory &mdash; the item is the one which was queried for and the list of results contains the identifiers of the related items. Here, notably, the order is important. Items near the top of the list rank higher than items further down.<br />
<br />
The only difference in the XML between an ''related'' and ''recommended'' query is the name of the element that the results are wrapped in.<br />
<br />
== Update examples ==<br />
<br />
: ''Do a complete update on the item user_1''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is the same format as we used for an import except that there's only one item. As noted in the [[REST API]] if this is PUT to an item it will overwrite all existing data.<br />
<br />
: ''Add or remove the tag "user" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>user</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is basically just a snippet from a usual item. One notable difference is that the item id may (but doesn't have to be) omitted for updating an item (using the add or remove methods noted in the API docs).<br />
<br />
: ''Remove the property "last name" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<property name="last name"></property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Similar to adding a tag, when removing a property it's worth noting that the value of the property is completely ignored.<br />
<br />
== XML header ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
</source><br />
<br />
Good old garden variety [[Wikipedia:XML|XML]] header. We prefer UTF-8, but we shouldn't blow up if you send us other stuff.<br />
<br />
== directededge element ==<br />
<br />
<source lang="xml"><br />
<directededge version="0.1"><br />
</source><br />
<br />
Nothing too exotic here for the moment. This wraps up all of the stuff that you'll send our receive for the moment. Version is always ''0.1'' for the moment because, well, we're too lazy to bump the version. (Though we'll do better versioning once we're out of beta.)<br />
<br />
== item element ==<br />
<br />
<source lang="xml"><br />
<item id='user_1'><br />
</source><br />
<br />
An item is the container for all of the stuff in our database. Exactly what items are is explained in [[API Concepts]].<br />
<br />
=== id attribute ===<br />
<br />
Every item ''must'' have an id attribute. That's the handle that we use to refer to the item everywhere. If you want to update or delete the item, you refer to it by its ''id''. You can use any scheme that you want to for creating item identifiers, so long as they're unique. Often something like ''type''_''number'' is convenient.<br />
<br />
== tag element ==<br />
<br />
Tags are always a child element of an ''item''. Tags can be free form as well. Usually they're things like ''user'', ''product'', ''page'', but they can also be much more specific like, ''artist'', ''album'', ''sci-fi'', etc. You can associate as many tags as you would like with a particular item.<br />
<br />
== property element ==<br />
<br />
<source lang="xml"><br />
<property name='last name'>Schmidt</property><br />
</source><br />
<br />
Properties are a set of key-value pairs associate with an item. Again, they are free form. You don't need to insert all of the values that you store locally in your database, in fact, most of the time you don't need to associate any at all. These are only useful if you later would like to grab data from the Directed Edge [[REST API]] about the items that you're storing there. You can associate as many properties with an item as you like, so long as their names are unique.<br />
<br />
=== name attribute ===<br />
<br />
Every property ''must'' have a name attribute. This can be anything that you like, but there may only be one property with a given name per item.<br />
<br />
== link element ==<br />
<br />
<source lang="xml"><br />
<link>product_1</link><br />
<link weight="3">product_2</link><br />
<link type="purchase">product_3</link><br />
</source><br />
<br />
The link element, surprise, surprise &mdash; indicates a link between two items. The identifiers used in the text, here ''product_1'', ''product_2'', and ''product_3'' are just the IDs of items in the database.<br />
<br />
'''Links to items that do not exist will be ignored unless those items are defined in the same import.''' In other words, if you have a link to an item that's defined lower in the same batch of XML, no problemo. But if you create a dead link, that just gets ignored.<br />
<br />
=== weight attribute ===<br />
<br />
The weight attribute is what we use for stuff like rankings. Weights can be in the range of 1 to 10 (or zero if you want to explicitly say there's no weight).<br />
<br />
So, if we want to say ''user_1 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== type attribute ===<br />
<br />
This specifies a type for the link. ''Link types'' can be imagined as a set of graphs superimposed upon each other. For example, in an e-commerce settings, these could be ''purchased'', ''rated'', ''category'', etc.<br />
<br />
You can then mix and match these ''types'' in recommendations &mdash; for example if you wanted to show related products based mostly on purchase, but also considering category information, you can specify that at query time. See our [[REST API]] for details on how to query link types.<br />
<br />
So, if we want to say ''user_1 purchaseds product_1 and product_2 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link type="purchase">product_1</link><br />
<link type="purchase">product_2</link><br />
<link type="rating" weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== ''weights'' vs. ''types'' ===<br />
<br />
There is both a semantic and practical different between weights and types.<br />
<br />
* '''Weights''' are used to represent things that are intrinsic to the data, but where the links being related are categorically similar. Ratings would be one notable example, repeat purchases would be another.<br />
<br />
* '''Types''' are used to specify different categories of relationships. For things that are categorically different, types have the advantage that they may be mixed and matched at query time rather than needing to be encoded, as with weights, at the time the data is uploaded to our service.<br />
<br />
== related element ==<br />
<br />
<source lang="xml"><br />
<related>user_1</related><br />
</source><br />
<br />
Totally no frills. Results from a ''related'' items query. Order matters.<br />
<br />
== recommended element ==<br />
<br />
<source lang="xml"><br />
<recommended>product_1</recommended><br />
</source><br />
<br />
Same deal as the related element, but for the results of ''recommended'' queries.<br />
<br />
== See also ==<br />
<br />
* [[Web Services Examples]]</div>Scotthttps://developer.directededge.com/index.php?title=XML_Format&diff=322XML Format2014-02-21T04:11:05Z<p>Scott: </p>
<hr />
<div>So, keeping in mind all of the basic structures from [[API Concepts]], let's see what they look like in XML.<br />
<br />
There are three major cases in which we'll get or send XML to the Directed Edge [[REST API]]:<br />
<br />
* '''Import / Export''' - this is just a list of all items with all of their links, properties and tags included.<br />
* '''Updates''' - you can update single items in the database or add or remove links, properties and tags.<br />
* '''Queries''' - for ''related'' or ''recommended'' items (there's a difference).<br />
<br />
The first two basically have the same form, with the notable difference that imports and exports contain multiple items, whereas updates only contain one item. Queries contain a list of item identifiers that are related to the query item.<br />
<br />
== Import / export example ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
<item id='product_1'><br />
<tag>product</tag><br />
<property name='artist'>Beatles</property><br />
<property name='name'>White Album</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Here we've got a customer, named ''Bob Schmidt'' that's connected to an album called ''The White Album'' by ''Beatles''. So we've got two [[item]]s and one [[link]]. Let's start breaking this down a little.<br />
<br />
If you imported this to your Directed Edge account using the [[REST API]], you'd have a database with two items. Similarly, if you requested a database export right after that, this is what you'd get back.<br />
<br />
'''Before you start sending XML to our server, we recommend passing it through [http://www.xmlsoft.org/xmllint.html xmllint] or similar to make sure that the XML is valid.''' The most common problem that we see with users that are new to the API is sending invalid XML and then our servers choking on it.<br />
<br />
== Related / recommended query example ==<br />
<br />
: ''Results for things related to "Web 2.0" in our Wikipedia database''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="Web 2.0"><br />
<related>Ajax (programming)</related><br />
<related>Delicious (website)</related><br />
<related>Flickr</related><br />
<related>Web service</related><br />
<related>RSS</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
The result structure here is pretty self-explanatory &mdash; the item is the one which was queried for and the list of results contains the identifiers of the related items. Here, notably, the order is important. Items near the top of the list rank higher than items further down.<br />
<br />
The only difference in the XML between an ''related'' and ''recommended'' query is the name of the element that the results are wrapped in.<br />
<br />
== Update examples ==<br />
<br />
: ''Do a complete update on the item user_1''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id='user_1'><br />
<link>product_1</link><br />
<tag>customer</tag><br />
<property name='last name'>Schmidt</property><br />
<property name='first name'>Bob</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is the same format as we used for an import except that there's only one item. As noted in the [[REST API]] if this is PUT to an item it will overwrite all existing data.<br />
<br />
: ''Add or remove the tag "user" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>user</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
This is basically just a snippet from a usual item. One notable difference is that the item id may (but doesn't have to be) omitted for updating an item (using the add or remove methods noted in the API docs).<br />
<br />
: ''Remove the property "last name" from an item''<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<property name="last name"></property><br />
</item><br />
</directededge><br />
</source><br />
<br />
Similar to adding a tag, when removing a property it's worth noting that the value of the property is completely ignored.<br />
<br />
== XML header ==<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
</source><br />
<br />
Good old garden variety [[Wikipedia:XML|XML]] header. We prefer UTF-8, but we shouldn't blow up if you send us other stuff.<br />
<br />
== directededge element ==<br />
<br />
<source lang="xml"><br />
<directededge version="0.1"><br />
</source><br />
<br />
Nothing too exotic here for the moment. This wraps up all of the stuff that you'll send our receive for the moment. Version is always ''0.1'' for the moment because, well, we're too lazy to bump the version. (Though we'll do better versioning once we're out of beta.)<br />
<br />
== item element ==<br />
<br />
<source lang="xml"><br />
<item id='user_1'><br />
</source><br />
<br />
An item is the container for all of the stuff in our database. Exactly what items are is explained in [[API Concepts]].<br />
<br />
=== id attribute ===<br />
<br />
Every item ''must'' have an id attribute. That's the handle that we use to refer to the item everywhere. If you want to update or delete the item, you refer to it by its ''id''. You can use any scheme that you want to for creating item identifiers, so long as they're unique. Often something like ''type''_''number'' is convenient.<br />
<br />
== tag element ==<br />
<br />
Tags are always a child element of an ''item''. Tags can be free form as well. Usually they're things like ''user'', ''product'', ''page'', but they can also be much more specific like, ''artist'', ''album'', ''sci-fi'', etc. You can associate as many tags as you would like with a particular item.<br />
<br />
== property element ==<br />
<br />
<source lang="xml"><br />
<property name='last name'>Schmidt</property><br />
</source><br />
<br />
Properties are a set of key-value pairs associate with an item. Again, they are free form. You don't need to insert all of the values that you store locally in your database, in fact, most of the time you don't need to associate any at all. These are only useful if you later would like to grab data from the Directed Edge [[REST API]] about the items that you're storing there. You can associate as many properties with an item as you like, so long as their names are unique.<br />
<br />
=== name attribute ===<br />
<br />
Every property ''must'' have a name attribute. This can be anything that you like, but there may only be one property with a given name per item.<br />
<br />
== link element ==<br />
<br />
<source lang="xml"><br />
<link>product_1</link><br />
<link weight="3">product_2</link><br />
<link type="purchase">product_3</link><br />
</source><br />
<br />
The link element, surprise, surprise &mdash; indicates a link between two items. The identifiers used in the text, here ''product_1'', ''product_2'', and ''product_3'' are just the IDs of items in the database.<br />
<br />
'''Links to items that do not exist will be ignored unless those items are defined in the same import.''' In other words, if you have a link to an item that's defined lower in the same batch of XML, no problemo. But if you create a dead link, that just gets ignored.<br />
<br />
=== weight attribute ===<br />
<br />
The weight attribute is what we use for stuff like rankings. Weights can be in the range of 1 to 10 (or zero if you want to explicitly say there's no weight).<br />
<br />
So, if we want to say ''user_1 gave product_1 a rating of 5'' that looks like this:<br />
<br />
<source lang="xml"><br />
<item id="user_1"><br />
<link weight="5">product_1</link><br />
</item><br />
</source><br />
<br />
=== type attribute ===<br />
<br />
This specifies a type for the link. ''Link types'' can be imagined as a set of graphs superimposed upon each other. For example, in an e-commerce settings, these could be ''purchased'', ''rated'', ''category'', etc.<br />
<br />
You can then mix and match these ''types'' in recommendations &mdash; for example if you wanted to show related products based mostly on purchase, but also considering category information, you can specify that at query time. See our [[REST API]] for details on how to query link types.<br />
<br />
=== ''weights'' vs. ''types'' ===<br />
<br />
There is both a semantic and practical different between weights and types.<br />
<br />
* '''Weights''' are used to represent things that are intrinsic to the data, but where the links being related are categorically similar. Ratings would be one notable example, repeat purchases would be another.<br />
<br />
* '''Types''' are used to specify different categories of relationships. For things that are categorically different, types have the advantage that they may be mixed and matched at query time rather than needing to be encoded, as with weights, at the time the data is uploaded to our service.<br />
<br />
== related element ==<br />
<br />
<source lang="xml"><br />
<related>user_1</related><br />
</source><br />
<br />
Totally no frills. Results from a ''related'' items query. Order matters.<br />
<br />
== recommended element ==<br />
<br />
<source lang="xml"><br />
<recommended>product_1</recommended><br />
</source><br />
<br />
Same deal as the related element, but for the results of ''recommended'' queries.<br />
<br />
== See also ==<br />
<br />
* [[Web Services Examples]]</div>Scotthttps://developer.directededge.com/index.php?title=Web_Services_Examples&diff=321Web Services Examples2014-01-14T22:43:40Z<p>Scott: </p>
<hr />
<div>So, now that you've been through the documentation on the [[API Concepts]], [[XML Format]] and [[REST API]], let's take a look at a few practical examples of working with the Directed Edge webservices.<br />
<br />
For these examples we'll be using the command line tool [http://curl.haxx.se/ curl] to upload XML to the webservices.<br />
<br />
== Importing a database ==<br />
<br />
Let's start with a very simple database with three users (with the IDs ''user1'', ''user2'' and ''user3'') and three products (with the IDs ''product1'', ''product2'' and ''product3'').<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="user1"><br />
<tag>user</tag><br />
<link>product1</link><br />
<link>product2</link><br />
</item><br />
<item id="user2"><br />
<tag>user</tag><br />
<link>product3</link><br />
</item><br />
<item id="user3"><br />
<tag>user</tag><br />
<link>product2</link><br />
</item><br />
<item id="product1"><br />
<tag>product</tag><br />
</item><br />
<item id="product2"><br />
<tag>product</tag><br />
</item><br />
<item id="product3"><br />
<tag>product</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|database}}<br />
<br />
This imports the structure above into the ''exampledb'' database.<br />
<br />
== Exporting a database ==<br />
<br />
{{CurlGet}}<br />
<br />
Produces:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="user1"><br />
<tag>user</tag><br />
<link>product1</link><br />
<link>product2</link><br />
</item><br />
<item id="user2"><br />
<tag>user</tag><br />
<link>product3</link><br />
</item><br />
<item id="user3"><br />
<tag>user</tag><br />
<link>product2</link><br />
</item><br />
<item id="product1"><br />
<tag>product</tag><br />
</item><br />
<item id="product2"><br />
<tag>product</tag><br />
</item><br />
<item id="product3"><br />
<tag>product</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
Which is what we imported just above.<br />
<br />
== Adding an item ==<br />
<br />
Adds a user with the ID ''user4'' to the database.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="user4"><br />
<tag>user</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|user4|/items/user4}}<br />
<br />
== Updating an item ==<br />
<br />
Here we update the item above, but this time add the property ''city''. This overwrites all current contents of the item.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item id="user4"><br />
<tag>user</tag><br />
<property name="city">Berlin</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|user4-update|/items/user4}}<br />
<br />
== Adding a tag to an item ==<br />
<br />
Here we add the tag ''Berliner'' to the user that we created / updated in the previous sections. As noted in the [[XML Format]] description, here we're allowed to omit the item's ID.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>Berliner</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|tag|/items/user4/add}}<br />
<br />
== Adding a link to an item ==<br />
<br />
This creates a link from our recently created user to ''product3''. Again, since we're updating the item we can omit the item ID.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<link>product3</link><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|link|/items/user4/add}}<br />
<br />
== Adding a property to an item ==<br />
<br />
Sets the value of the property ''country'' to ''Germany''.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<property name="country">Germany</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|property|/items/user4/add}}<br />
<br />
== Add several tags / properties / links to an item ==<br />
<br />
Just like you can add single tags, properties or links to an item, you can also add (or remove) several at a time:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>German</tag><br />
<property name="first name">Matthias</property><br />
<property name="last name">Schmidt</property><br />
<link>product2</link><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|several|/items/user4/add}}<br />
<br />
== Removing a tag from an item ==<br />
<br />
Just like we could add a tag to an item incrementally, we can remove a tag (or property, or link) by uploading the same content to the ''remove'' sub-resource.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<tag>Berliner</tag><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|tag|/items/user4/remove}}<br />
<br />
== Removing a link from an item ==<br />
<br />
And now we can do the same with removing the link to ''product3'':<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<directededge version="0.1"><br />
<item><br />
<link>product3</link><br />
</item><br />
</directededge><br />
</source><br />
<br />
{{CurlPut|link|/items/user4/remove}}<br />
<br />
== Retrieving an item ==<br />
<br />
Now that we've made a number of changes to the item that we've been working with, let's see what the current state of it in the database is:<br />
<br />
{{CurlGet|/items/user4}}<br />
<br />
Produces:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="user4"><br />
<tag>German</tag><br />
<tag>user</tag><br />
<link>product2</link><br />
<property name="first name">Matthias</property><br />
<property name="last name">Schmidt</property><br />
<property name="city">Berlin</property><br />
<property name="country">Germany</property><br />
</item><br />
</directededge><br />
</source><br />
<br />
== Deleting an item ==<br />
<br />
And now let's clear out the item we've been working with from the database.<br />
<br />
{{CurlGet|/items/user4|argument=-X DELETE}}<br />
<br />
== Finding related items ==<br />
<br />
Let's get the related items for ''product1'':<br />
<br />
{{CurlGet|/items/product1/related}}<br />
<br />
Gives us all related items:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="product1"><br />
<related>product2</related><br />
<related>user1</related><br />
<related>user3</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
Hmm, well, that's not quite what we wanted, but have no fear, this is where the ''tags'' query attribute comes in handy:<br />
<br />
{{CurlGet|/items/product1/related\?tags&#61;product}}<br />
<br />
And now we get back just items with the ''product'' tag:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="product1"><br />
<related>product2</related><br />
</item><br />
</directededge><br />
</source><br />
<br />
== Doing personalized recommendations ==<br />
<br />
Note that when we want to do personalized recommendations we use the ''recommended'' pseudo-resource rather than ''related''. Our servers do a little different of a sort of magic for producing personalized recommendations than are used to find related products or pages.<br />
<br />
{{CurlGet|/items/user3/recommended}}<br />
<br />
Here are the personalized recommendations for ''user3''.<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="user3"><br />
<recommended>user1</recommended><br />
<recommended>product2</recommended><br />
<recommended>product1</recommended><br />
</item><br />
</directededge><br />
</source><br />
<br />
But here we also get a user in the result set &mdash; just as above we want to specify the tags that we're interested in:<br />
<br />
{{CurlGet|/items/user3/recommended\?tags&#61;product}}<br />
<br />
Which now gives us only product results:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="user3"><br />
<recommended>product2</recommended><br />
<recommended>product1</recommended><br />
</item><br />
</directededge><br />
</source><br />
<br />
So, now we get just products back, but ''user3'' is already connected to ''product2'' &mdash; meaning we assume that they've already purchased or rated it, so we don't actually want that in the result set. So let's throw in the ''excludeLinked=true''.<br />
<br />
{{CurlGet|/items/user3/recommended\?tags&#61;product\&excludeLinked&#61;true}}<br />
<br />
Now we get only things tagged ''product'' and none of the ones that the user already has a connection to:<br />
<br />
<source lang="xml"><br />
<?xml version="1.0" standalone="yes"?><br />
<br />
<directededge version="0.1"><br />
<item id="user3"><br />
<recommended>product1</recommended><br />
</item><br />
</directededge><br />
</source><br />
<br />
And there we have the (admittedly short) list of personalized recommendations for ''user3''.</div>Scotthttps://developer.directededge.com/index.php?title=REST_API&diff=320REST API2014-01-14T22:35:57Z<p>Scott: </p>
<hr />
<div>The Directed Edge [[Wikipedia:REST|REST]] API is a fairly simple way of modeling a collection of items and the relationships between them. These relationships are used as the basis for finding similar items or delivering personalized recommendations to a user. Information is encoded using our [[XML Format]] using notions from the [[API Concepts]].<br />
<br />
REST APIs allow for using the [[Wikipedia:Hypertext Transfer Protocol#Request_methods|HTTP methods]] GET, PUT, POST and DELETE on various resources. Resources are just normal URLs organized hierarchically. In our case there is the database, items and things you can do with items (query, update, etc.).<br />
<br />
Let's have a look at an example URL:<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/}}</tt><br />
<br />
This is the URL for the wikipedia database. Many of the elements are constant &mdash; notably the host name, and the "api/v1" sections. We'll break down the other resources and the methods allowed on them in the following sections.<br />
<br />
== HTTP and HTTPS ==<br />
<br />
The Directed Edge API allows for both HTTP and secured HTTPS connections. HTTPS tends to incur a slightly higher latency since setting up the connection is more involved.<br />
<br />
== API Authentication ==<br />
<br />
We use HTTP Basic authentication exclusively at the moment. HTTP Basic just means a user name and password that you stick at the front of the URL, just like if you were connecting to an FTP site. For example:<br />
<br />
<tt>{{URL||user:password|@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/}}</tt><br />
<br />
When your account was created for use with the Directed Edge recommendation engine you should have been send a user name and a (usually freakishly long) password. In general the user name is the same as the database name. We can reset your password for you at any time, but can not provide your current password if you lose it.<br />
<br />
== Database resource ==<br />
<br />
: ''Example of Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/|wikipedia|/}}</tt><br />
<br />
The database is the mothership of items &mdash; it's just one big set of items and those items are connected to other stuff and whatnot. The methods that you typically want to run on a database are importing and exporting it, which map conveniently to the GET and PUT methods. Check out the documentation on the [[XML Format]] to figure out what the data you send should look like.<br />
<br />
Also note that your database name is the same as your user name.<br />
<br />
=== Add sub-resource ===<br />
<br />
You can incrementally do batch updates to the database by appending ''add'' to the end of the URL. The XML format is the same as for a normal import, but it will not first clear the database the items in the database will be the combination of previously existing data, plus the new data. Specifically, if you already had an item with some links and tags and wanted to add another tag, you would enter that item with no data other than the new tag and the result would be an item with those properties and links, plus the new tag.<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/|add|}}</tt><br />
<br />
<br />
=== HTTP GET ===<br />
<br />
Used to dump the database including all items, links, properties and tags to XML. You can use this to grab a snapshot of your database at any point in time. However, please do this sparingly since it naturally hits the database pretty hard.<br />
<br />
=== HTTP PUT ===<br />
<br />
Used to import a dump of a database. You can create those dumps either by exporting the current database (using the GET method above), with our language bindings (Ruby only, for the moment) or in your programming language of choice in our [[XML Format]]. Note that '''this will overwrite all content currently in your database'''.<br />
<br />
== Item resource ==<br />
<br />
: ''Example of the '"Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/|Miles%20Davis|/}}</tt><br />
<br />
Items are the bread and butter of the Directed Edge recommendations engine. As noted in the [[API Concepts]], ''everything is an item''. Items contain must have an identifier, which is the part highlighted in the URL above. That can be anything you want, but naturally, when used as part of the resource name, must be URL encoded. (The language bindings handle that for you.)<br />
<br />
=== HTTP GET ===<br />
<br />
This retrieves the item with all of its tags, properties and links. See [[XML Format]] for a description of the data you'd expect here.<br />
<br />
=== HTTP PUT ===<br />
<br />
Updates or creates an item overwriting all of its current contents. The item identifier used in the XML must match the resource name that you're updating or creating. This may contain tags, properties and links and will overwrite all of the current data associated with this item. Items that ''link'' to this item will not be affected.<br />
<br />
=== HTTP DELETE ===<br />
<br />
Removes the item from the database. This also removes all incoming links (from other items) pointing to this item.<br />
<br />
=== Add and remove sub-resources ===<br />
<br />
: ''Examples of adding or removing bits of the "Miles Davis" item in the Wikipedia database''<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|add}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|remove}}</tt><br />
<br />
Here we break a little bit from traditional REST dogma by adding pseudo-resources that let you do partial updates of resources. The pure at heart can still stick to the item resource above and rely on it for updating items wholesale.<br />
<br />
The add and remove sub-resources allow you to add / remove tags, links or properties incrementally. You don't have to worry about race conditions between pulling down the content of a resource and updating it in the database.<br />
<br />
The typical use cases are adding a tag to a given item, or removing a property.<br />
<br />
The [[XML Format]] docs also explain that you may omit certain parts of the typical item XML for convenience.<br />
<br />
==== HTTP PUT ====<br />
<br />
In the case of calling '''add''' any tags, properties or links that you've put in the XML will be incrementally updated in the database. If those values already exist, they'll simply be ignored.<br />
<br />
Calling '''remove''', similarly, does an incremental ''removal'' of those tags, links or properties from the database. This one is the quirkiest to think about because you're doing a PUT to a REST resource and it removes stuff, but in practice this is a convenient way of removing little bits of the content of a given item.<br />
<br />
== Related / recommended resources ==<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/|related}}</tt><br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/somestore/items/user12345/|recommended}}</tt><br />
<br />
Now we get to the business end of the API &mdash; the reason that you're here in the first place. Here again we break a little from the typical REST dogma by creating resources for information that's computed on the fly.<br />
<br />
'''The first thing to note here is that ''related'' and ''recommended'' are subtlety different.'''<br />
<br />
''Related'' is used for finding ''similar'' things. For instance, a friend finder in a social network would use the ''related'' method. Similarly, if you wanted to find ''similar'' products in an online store, again, ''related'' is the thing that you're looking for.<br />
<br />
: ''Here's what these look like in Amazon:''<br />
<br />
[[Image:Amazon-related.png]]<br />
<br />
''Recommended'' on the other hand uses a magic of a slightly different sort to find ''personalized recommendations''. You know, ''"Hi Bob, here are some books that we think you'll like..."'' Again we'll defer to Amazon:<br />
<br />
: ''Amazon showing personalized recommendations:''<br />
<br />
[[Image:Amazon-recommendations.png]]<br />
<br />
The ''item'' used for the ''recommended'' query should usually be a user. Recommended is also usually used in conjunction with the ''exlcludeLinked'' query parameter mentioned below.<br />
<br />
''Related'' and ''recommended'' form the core of the mathematical heavy lifting that Directed Edge does for your site. In a sense, everything else that you can do with the Directed Edge database is built up to getting the most out of these recommendations.<br />
<br />
=== HTTP GET ===<br />
<br />
So, now that you know what ''related'' and ''recommended'' are about, fetching their content is pretty trivial. You just send a get request to our servers and the top items will be returned in an [[XML Format|XML]] list. '''The order matters here'''. The top items are at the top of the list and ranked in descending order.<br />
<br />
=== Query Parameters ===<br />
<br />
There are a couple of ways that you can shape the results that are returned from ''related'' or ''recommended'' queries.<br />
<br />
==== excludeLinked query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|excludeLinked&#61;true}}</tt><br />
<br />
This parameter is most often used in conjunction with ''recommended'' queries. You remember from our [[API Concepts]] that a link is any relationship between items? Well, usually when you're recommending items to a user, you want to avoid recommending things that they've already interacted with &mdash; products that they've already bought, for instance.<br />
<br />
So, there you just add the handy ''excludeLinked'' parameter to the end of the query and the user will only see recommendations for things they haven't already bought / rated / clicked on / etc.<br />
<br />
==== tags query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|tags&#61;product,page}}</tt><br />
<br />
Again, from the [[API Concepts]] you should be familiar with ''tags'' within the Directed Edge data model. Most users of the API have broadly things that generalize to ''users'' and ''products'', and you often only want to recommend items matching one of those tags.<br />
<br />
So, to drive the recommended products for a given user, you'd just slap on the ''tags=product'' to the end of the query string and presto, you'll only get results that have the ''product'' tag.<br />
<br />
You can pass in as many tags as you like. They're logically connected via a ''logical or'' &mdash; meaning that products that have ''any'' of the tags that you specify will be included in the results.<br />
<br />
==== maxResults query parameter ====<br />
<br />
<tt>{{URL|username:password@webservices.directededge.com/api/v1/wikipedia/items/Miles%20Davis/related?|maxResults&#61;5}}</tt><br />
<br />
This one's really simple: it specifies the number of results that you're interested in receiving from ''related'' or ''recommended'' queries. If you're feeling particularly charitable, set this to the number of items that you actually display on your site and save our servers the trouble of finding results that you're not interested in.</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=319Recommendation parameters2014-01-10T19:40:34Z<p>Scott: </p>
<hr />
<div>''List'' parameters are just a comma separated list of strings, defaulting to an empty list.<br />
<br />
{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ Add, Subtract, Replace ]<br />
| updateMethod<br />
| Replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=318Recommendation parameters2014-01-06T20:57:58Z<p>Scott: </p>
<hr />
<div>''List'' parameters are just a comma separated list of strings, defaulting to an empty list.<br />
<br />
{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" or "excludedTags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ Add, Subtract, Replace ]<br />
| updateMethod<br />
| Replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=317Recommendation parameters2014-01-06T20:41:21Z<p>Scott: </p>
<hr />
<div>{| class="wikitable"<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
| Only include items which possess the specified tags<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
| Exclude items which possess the specified tags<br />
|-<br />
| list<br />
| exclude<br />
| <br />
| Exclude the items with the given IDs<br />
|-<br />
| list<br />
| items<br />
| <br />
| For a database-related request (i.e. basket request), specifies the list of items to find related items to; for a normal database GET request, specifies which items should be returned (useful for getting information about a number of items at once)<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
| Show the "references" (back-links) for an item GET<br />
|-<br />
| list<br />
| ignore<br />
| <br />
| Do not include or factor into ranking the listed IDs<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false (recommended) / true (related)<br />
| Don't include the items directly linked from the query item (i.e. products already purchased by a customer)<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
| The maximum number of recommended entries to return<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
| Include the properties for the item as XML attributes in a related or recommended query<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
| Include the tags for the item as an XML attribute (comma separated) in a related or recommended query<br />
|-<br />
| list<br />
| include<br />
| <br />
| Hand-pick the listed IDs for inclusion in a recommended or related query<br />
|-<br />
| string<br />
| tagOperation<br />
| OR<br />
| Specifies whether the list of tags specified in "tags" or "excludedTags" should be evaluated using a logical "or" or logical "and"<br />
|-<br />
| enum [ Add, Subtract, Replace ]<br />
| updateMethod<br />
| Replace<br />
| Specifies the behavior POSTed updates to items<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
| Ranks a specific set of items using the "related" method<br />
|-<br />
| float (0 .. 1.0)<br />
| popularity<br />
| -1.0 (automatic)<br />
| Skews results towards more niche or popular items<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Recommendation_parameters&diff=316Recommendation parameters2014-01-03T21:59:54Z<p>Scott: Created page with "{| ! Type ! Name ! Default ! Description |- | list | tags | | |- | list | excludedTags | | |- | list | exclude | | |- | list | items | | |- | boolean | includeUnranked | fals..."</p>
<hr />
<div>{|<br />
! Type<br />
! Name<br />
! Default<br />
! Description<br />
|-<br />
| list<br />
| tags<br />
| <br />
|<br />
|-<br />
| list<br />
| excludedTags<br />
| <br />
|<br />
|-<br />
| list<br />
| exclude<br />
| <br />
|<br />
|-<br />
| list<br />
| items<br />
| <br />
|<br />
|-<br />
| boolean<br />
| includeUnranked<br />
| false<br />
|<br />
|-<br />
| boolean<br />
| showReferences<br />
| false<br />
|<br />
|-<br />
| list<br />
| ignore<br />
| <br />
|<br />
|-<br />
| boolean<br />
| excludeLinked<br />
| false<br />
|<br />
|-<br />
| boolean<br />
| createMissingLinks<br />
| false<br />
|<br />
|-<br />
| int<br />
| maxResults<br />
| 20<br />
|<br />
|-<br />
| boolean<br />
| countOnly<br />
| false<br />
|<br />
|-<br />
| boolean<br />
| includeProperties<br />
| false<br />
|<br />
|-<br />
| boolean<br />
| includeTags<br />
| false<br />
|<br />
|-<br />
| list<br />
| include<br />
| <br />
|<br />
|-<br />
| string<br />
| tagOperation<br />
| "OR"<br />
|<br />
|-<br />
| enum<br />
| updateMethod<br />
| DatabaseItemXMLHandler.UpdateMethod.Replace<br />
|<br />
|-<br />
| list<br />
| itemsToRank<br />
| <br />
|<br />
|-<br />
| float<br />
| popularity<br />
| (float) -1.0<br />
|<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=API_Concepts&diff=315API Concepts2014-01-03T19:39:00Z<p>Scott: </p>
<hr />
<div>Directed Edge's recommendation engine is built on top of our [http://blog.directededge.com/2009/02/27/on-building-a-stupidly-fast-graph-database/ in-house database]. The database works somewhat differently than traditional databases and its interface is our [[REST API]], so it's useful before getting started to have a feel for how to go about translating things from the way that your site models data to the way that our database works.<br />
<br />
== Everything is an item, or ''A brief introduction to schema-less databases'' ==<br />
<br />
[[Image:user-item.png|user-item.png]][[Image:product-item.png]]<br />
<br />
'''Users, products, places, web pages &mdash; they're all items for us.'''<br />
<br />
Really? Yep. Above are a couple of examples of things that could be items in our database.<br />
<br />
=== Unique Identifiers ===<br />
<br />
Items have an identifier (''user_1'' and ''product_1'' in the example above). That can't be changed once it's imported to the database. It's the handle that we use to grab a hold of things later on. These ''must'' be unique. Otherwise the database doesn't know how to tell two items apart. You can use any scheme that you like to encode these. Most people just use something like the type of the object (product, for example) and then the numeric ID that's stored in their SQL database, but you could also use the URL to a page here or anything else that makes sense for your data.<br />
<br />
=== Tags ===<br />
<br />
Items can also have a collection of text tags. These are useful in filtering results later on. If you, for instance, wanted to find all of the books that are recommended for a certain user, it'd be useful to have some items tagged as ''book''. You can also give an item as many tags as you want, so it's no problem to have ''product'', ''book'' and ''sci-fi'' all associated with the same item.<br />
<br />
Note however, that tags are just ways that we can label items; they're not actively used in finding similar items.<br />
<br />
=== Properties ===<br />
<br />
[[Image:database-table.png|right|250px|]]<br />
<br />
Properties are almost as simple. They're just a bunch of key-value pairs that are associated with a given item. Unlike in a traditional database where you'd have a [[Wikipedia:Database schema|schema]] for your users table, another one for your products table and another one for ... well, whatever else you wanted to store, properties in the Directed Edge database are completely ad-hoc.<br />
<br />
Just to get the gears turning in your head, examples of things that can be stored in properties are: price, address, first name, last name, author, etc. Pretty much all of the standard fare that would go into a database column.<br />
<br />
If you've got some products that have a property named ''price'' and some that don't, that's just fine with us.<br />
<br />
At the moment properties aren't used at all by the recommendations algorithms, but we may add support for doing that later. For now they're just a convenient way of keeping tabs on the information that is being recommended.<br />
<br />
== Links, or ''the way you connect stuff'' ==<br />
<br />
So, we're huge [[Wikipedia:Graph theory|graph theory]] wonks. No, no, not like Excel. Like webs of information.<br />
<br />
[[Image:graph.png]]<br />
<br />
In computer science lingo, a graph is just a sets of connections between items. Those connections are called ''edges'' and the items are called ''nodes''. All sorts of things can be modeled in graphs, like the way that web pages are connected to each other (there the links between pages are ''edges''), or as above, a set of friends in a social network.<br />
<br />
'''Let's make this really easy just to be clear: ''a graph is just a collection of connected stuff.'' '''<br />
<br />
Here's an example of the two ''items'' from above connected via an ''edge''. This would indicate, for instance, that the user had bought that product.<br />
<br />
[[Image:user-product-link.png]]<br />
<br />
'''An ''edge'' is just the math term for what we call a ''link''. They're the connections.'''<br />
<br />
Every ''object'' in the Directed Edge database is an ''item''; the relationships between them are ''links''.<br />
<br />
=== Examples of links ===<br />
<br />
* A '''user (item) purchases a product (item)''', so we make a link from the user to the product.<br />
* A '''user (item) gives a rating of 5 to a product (item)''', so we create a link between the user and the product with a ''weight'' of 5.<br />
* A '''user (item) clicks on a product category (item)''', so we make a link from the user to the category page.<br />
* A '''user (item) is friends with another user (item)''', so we make a link from the user to the other user.<br />
* A '''user (item) is a fan of a band (item)''', so we make a link from the user to the band.<br />
* A '''web page (item) is connected to another web page (item)''', so we make a link from the first page to the second page (just mimicking the HTML link structure).<br />
<br />
So when getting up and going with the Directed Edge system, you have to decide which bits of information you want to base the recommendations on.<br />
<br />
=== Directed edges ===<br />
<br />
You notice up there that those arrows aren't bi-directional? They don't have a pointy thing on both sides? Well, guess where the name of our company comes from: those are ''directed edges''. In graph theory you can have undirected edges and directed edges. All that ''directed'' means here is that they have a direction. A connection from ''A'' to ''B'' is not the same as a connection from ''B'' to ''A''. One says, ''Bob is a friend of Sarah'' and another implies ''Sarah is a friend of Bob''.<br />
<br />
Web page ''A'' can link to web page ''B'' without implying that web page ''B'' also links back to web page ''A''. That link is a ''directed edge''.<br />
<br />
It's the same kind of deal when a user buys a product. We usually want to represent ''a user bought a product'' rather than implying that the product has some sort of fundamental connection with the user (though it might, for instance, if the user was also the author of it).<br />
<br />
The only typical use case where this matters in using the API is that if you have friends in a social network, and the friendships are reciprocal (like Facebook) rather than possibly uni-directional (like Twitter), you have to put ''two'' links in there to convey the friendship.<br />
<br />
=== Link types ===<br />
<br />
We've also introduced the notion of ''typed links''. '''Typed links''' specify something like:<br />
<br />
: ''The relationship between this customer and this product is '''purchase'''.''<br />
<br />
'''Link types can be mixed and matched at query time.''' So if you're asking for ''related products'' you can ask for a mix of recommendations based 80% on purchases and 20% on common tags by saying that you'd like 0.8 of the ''purchase'' link type and 0.2 of the ''tag'' link type.<br />
<br />
You can create whatever link types seem appropriate for your site's data.<br />
<br />
== See Also ==<br />
<br />
* [[Introduction to Recommendations]] for the basics on how recommendations work.<br />
* [[XML Format]] for information on how to represent these lovely concepts in simple XML.<br />
* [[REST API]] for documentation on communicating with our webservices.</div>Scotthttps://developer.directededge.com/index.php?title=API_Concepts&diff=314API Concepts2014-01-03T19:38:23Z<p>Scott: </p>
<hr />
<div>Directed Edge's recommendation engine is built on top of our [http://blog.directededge.com/2009/02/27/on-building-a-stupidly-fast-graph-database/ in-house database]. The database works somewhat differently than traditional databases and its interface is our [[REST API]], so it's useful before getting started to have a feel for how to go about translating things from the way that your site models data to the way that our database works.<br />
<br />
== Everything is an item, or ''A brief introduction to schema-less databases'' ==<br />
<br />
[[Image:user-item.png|user-item.png]][[Image:product-item.png]]<br />
<br />
'''Users, products, places, web pages &mdash; they're all items for us.'''<br />
<br />
Really? Yep. Above are a couple of examples of things that could be items in our database.<br />
<br />
=== Unique Identifiers ===<br />
<br />
Items have an identifier (''user_1'' and ''product_1'' in the example above). That can't be changed once it's imported to the database. It's the handle that we use to grab a hold of things later on. These ''must'' be unique. Otherwise the database doesn't know how to tell two items apart. You can use any scheme that you like to encode these. Most people just use something like the type of the object (product, for example) and then the numeric ID that's stored in their SQL database, but you could also use the URL to a page here or anything else that makes sense for your data.<br />
<br />
=== Tags ===<br />
<br />
Items can also have a collection of text tags. These are useful in filtering results later on. If you, for instance, wanted to find all of the books that are recommended for a certain user, it'd be useful to have some items tagged as ''book''. You can also give an item as many tags as you want, so it's no problem to have ''product'', ''book'' and ''sci-fi'' all associated with the same item.<br />
<br />
Note however, that tags are just ways that we can label items; they're not actively used in finding similar items.<br />
<br />
=== Properties ===<br />
<br />
[[Image:database-table.png|right|250px|]]<br />
<br />
Properties are almost as simple. They're just a bunch of key-value pairs that are associated with a given item. Unlike in a traditional database where you'd have a [[Wikipedia:Database schema|schema]] for your users table, another one for your products table and another one for ... well, whatever else you wanted to store, properties in the Directed Edge database are completely ad-hoc.<br />
<br />
Just to get the gears turning in your head, examples of things that can be stored in properties are: price, address, first name, last name, author, etc. Pretty much all of the standard fare that would go into a database column.<br />
<br />
If you've got some products that have a property named ''price'' and some that don't, that's just fine with us.<br />
<br />
At the moment properties aren't used at all by the recommendations algorithms, but we may add support for doing that later. For now they're just a convenient way of keeping tabs on the information that is being recommended.<br />
<br />
== Links, or ''the way you connect stuff'' ==<br />
<br />
So, we're huge [[Wikipedia:Graph theory|graph theory]] wonks. No, no, not like Excel. Like webs of information.<br />
<br />
[[Image:graph.png]]<br />
<br />
In computer science lingo, a graph is just a sets of connections between items. Those connections are called ''edges'' and the items are called ''nodes''. All sorts of things can be modeled in graphs, like the way that web pages are connected to each other (there the links between pages are ''edges''), or as above, a set of friends in a social network.<br />
<br />
'''Let's make this really easy just to be clear: ''a graph is just a collection of connected stuff.'' '''<br />
<br />
Here's an example of the two ''items'' from above connected via an ''edge''. This would indicate, for instance, that the user had bought that product.<br />
<br />
[[Image:user-product-link.png]]<br />
<br />
'''An ''edge'' is just the math term for what we call a ''link''. They're the connections.'''<br />
<br />
Every ''object'' in the Directed Edge database is an ''item''; the relationships between them are ''links''.<br />
<br />
=== Examples of links ===<br />
<br />
* A '''user (item) purchases a product (item)''', so we make a link from the user to the product.<br />
* A '''user (item) gives a rating of 5 to a product (item)''', so we create a link between the user and the product with a ''weight'' of 5.<br />
* A '''user (item) clicks on a product category (item)''', so we make a link from the user to the category page.<br />
* A '''user (item) is friends with another user (item)''', so we make a link from the user to the other user.<br />
* A '''user (item) is a fan of a band (item)''', so we make a link from the user to the band.<br />
* A '''web page (item) is connected to another web page (item)''', so we make a link from the first page to the second page (just mimicking the HTML link structure).<br />
<br />
So when getting up and going with the Directed Edge system, you have to decide which bits of information you want to base the recommendations on.<br />
<br />
=== Directed edges ===<br />
<br />
You notice up there that those arrows aren't bi-directional? They don't have a pointy thing on both sides? Well, guess where the name of our company comes from: those are ''directed edges''. In graph theory you can have undirected edges and directed edges. All that ''directed'' means here is that they have a direction. A connection from ''A'' to ''B'' is not the same as a connection from ''B'' to ''A''. One says, ''Bob is a friend of Sarah'' and another implies ''Sarah is a friend of Bob''.<br />
<br />
Web page ''A'' can link to web page ''B'' without implying that web page ''B'' also links back to web page ''A''. That link is a ''directed edge''.<br />
<br />
It's the same kind of deal when a user buys a product. We usually want to represent ''a user bought a product'' rather than implying that the product has some sort of fundamental connection with the user (though it might, for instance, if the user was also the author of it).<br />
<br />
The only typical use case where this matters in using the API is that if you have friends in a social network, and the friendships are reciprocal (like Facebook) rather than possibly uni-directional (like Twitter), you have to put ''two'' links in there to convey the friendship.<br />
<br />
=== Link types ===<br />
<br />
We've also introduced the notion of ''typed links''. '''Typed links''' specify something like:<br />
<br />
: ''The relationship between this customer and this product is '''purchase'''.''<br />
<br />
Link types can be mixed and matched at query time. So if you're asking for ''related products'' you can ask for a mix of recommendations based 80% on purchases and 20% on common tags by saying that you'd like 0.8 of the ''purchase'' link type and 0.2 of the ''tag'' link type.<br />
<br />
You can create whatever link types seem appropriate for your site's data.<br />
<br />
== See Also ==<br />
<br />
* [[Introduction to Recommendations]] for the basics on how recommendations work.<br />
* [[XML Format]] for information on how to represent these lovely concepts in simple XML.<br />
* [[REST API]] for documentation on communicating with our webservices.</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=313Shopify Liquid2013-10-23T18:25:40Z<p>Scott: </p>
<hr />
<div>See also our page with [[Shopify Liquid Examples]].<br />
<br />
== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in our [http://shopify.directededge.com/settings#styling Appearance Settings].<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}<br />
<br />
<br />
=== <tt>product</tt> ===<br />
<br />
We support the same variables as Shopify. See their documentation for <tt>[http://docs.shopify.com/themes/liquid-variables/product product]</tt>.</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=312Shopify Liquid2013-10-23T18:24:05Z<p>Scott: </p>
<hr />
<div>See also [[Shopify Liquid Examples]].<br />
<br />
== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in our [http://shopify.directededge.com/settings#styling Appearance Settings].<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}<br />
<br />
<br />
=== <tt>product</tt> ===<br />
<br />
We support the same variables as Shopify. See their documentation for <tt>[http://docs.shopify.com/themes/liquid-variables/product product]</tt>.</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=311Shopify Liquid Examples2013-10-23T18:04:11Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Note that in general you'll probably want to incorporate the CSS that's here into your site's main CSS file(s), but it's included here to make the examples more complete and usable out of the box.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Basic Example (Plain-text output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
</div><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Default ==<br />
<br />
This is a simple, but usable style that's shown by default when you switch to the custom layout mode. It features a simple list of up to 5 products per recommendations type, plus bundles. Products are shown with a simple 5 pixel border. This is a responsive style.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="recommendations-product"><br />
<div class="recommendations-product-image"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
</div><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
<br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
clear: both;<br />
}<br />
.recommendations-group .recommendations-product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .recommendations-product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .recommendations-product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
.recommendations-product-image {<br />
position: relative;<br />
bottom: 0px;<br />
height: 180px;<br />
}<br />
.recommendations-product-image img {<br />
position: absolute;<br />
bottom: 0px;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
margin-bottom: 1em;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em;<br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em;<br />
}<br />
</style><br />
</source><br />
</div><br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=310Shopify Liquid Examples2013-10-23T17:53:51Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Basic Example (Plain-text output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
</div><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Default ==<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="recommendations-product"><br />
<div class="recommendations-product-image"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
</div><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
<br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
clear: both;<br />
}<br />
.recommendations-group .recommendations-product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .recommendations-product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .recommendations-product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
.recommendations-product-image {<br />
position: relative;<br />
bottom: 0px;<br />
height: 180px;<br />
}<br />
.recommendations-product-image img {<br />
position: absolute;<br />
bottom: 0px;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
margin-bottom: 1em;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em;<br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em;<br />
}<br />
</style><br />
</source><br />
</div><br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=309Shopify Liquid Examples2013-10-23T17:53:22Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Basic Example (Plain-text output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
</div><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Default ==<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em; <br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
padding: 1em 0;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em; <br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div><br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=308Shopify Liquid Examples2013-10-23T17:52:16Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Default ==<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em; <br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
padding: 1em 0;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em; <br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div><br />
<br />
== Basic Example (Textual output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
</div><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<div class="shopify-custom-style"><br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
</div></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=307Shopify Liquid Examples2013-10-23T17:26:27Z<p>Scott: </p>
<hr />
<div>Here are a few examples of custom styles that can be used in the Directed Edge custom style engine for Shopify.<br />
<br />
Also see our [[Shopify Liquid|variable reference]].<br />
<br />
== Default ==<br />
<br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em; <br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
padding: 1em 0;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em; <br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
<br />
== Basic Example (Textual output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=306Shopify Liquid2013-10-23T17:25:10Z<p>Scott: </p>
<hr />
<div>See also [[Shopify Liquid Examples]].<br />
<br />
== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in our [http://shopify.directededge.com/settings#styling Appearance Settings].<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=305Shopify Liquid Examples2013-10-16T18:02:38Z<p>Scott: </p>
<hr />
<div>== Default ==<br />
<br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
vertical-align: top;<br />
width: 200px;<br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img, #bundle img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
#bundle > *{<br />
vertical-align: middle;<br />
}<br />
#bundle .bundle-plus {<br />
font-size: 3em; <br />
}<br />
#bundle .bundle-label {<br />
font-size: 1.5em;<br />
display: inline-block;<br />
padding: 1em 0;<br />
}<br />
#bundle .bundle-last {<br />
margin-right: 0.5em; <br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><br />
<img class="bundle-first" src="{{ group.products.first.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-plus">+</span><br />
<img class="bundle-last" src="{{ group.products.last.featured_image | product_img_url: 'compact' }}" /><br />
<span class="bundle-label"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></span><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
<br />
== Basic Example (Textual output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=304Shopify Liquid Examples2013-10-12T07:09:37Z<p>Scott: </p>
<hr />
<div>== Default ==<br />
<br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
width: 200px;<br />
vertical-align: top; <br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></div><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
<br />
== Basic Example (Textual output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid_Examples&diff=303Shopify Liquid Examples2013-10-12T07:08:49Z<p>Scott: </p>
<hr />
<div>== Default ===<br />
<br />
<source lang="xml"><br />
<style type="text/css" media="screen"><br />
#recommendations h3, .recommendations-group {<br />
padding: 0.5em 0;<br />
}<br />
.recommendations-group .product {<br />
display: inline-block;<br />
width: 200px;<br />
vertical-align: top; <br />
padding-bottom: 0.5em;<br />
}<br />
.recommendations-group .product div {<br />
margin: 0.5em 0;<br />
}<br />
.recommendations-group .product img {<br />
border: 10px solid #f6f6f6;<br />
}<br />
</style><br />
<br />
<div id="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendations-group"><br />
<h3>{{ group.label }}</h3><br />
{% if group.bundle %}<br />
<div id="bundle"><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></div><br />
{% else %}<br />
{% for product in group.products limit:10 %}<br />
<div class="product"><br />
<a href="{{ product.url }}"><img src="{{ product.featured_image | product_img_url: 'compact' }}"></a><br />
<div class="title"><a href="{{ product.url }}">{{ product.title }}</a></div><br />
<div class="price">{{ product.price | money }}</div><br />
</div><br />
{% endfor %}<br />
{% endif %}<br />
</div><br />
{% endfor %}<br />
</div><br />
</source><br />
<br />
== Basic Example (Textual output) ==<br />
This basic example demonstrates iterating through different recommendation types (called <tt>groups</tt>) and listing a maximum of five recommended products per group in a nested iteration:<br />
<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<h3>{{ group.label }}</h3><br />
<ul><br />
{% if group.bundle %}<br />
<li><a href="{{ bundle.buy_link }}">{{ bundle.text }}</a></li><br />
{% else %}<br />
{% for product in group.products limit:5 %}<br />
<li><br />
<a href="{{ product.url }}">{{ product.title }}</a><br />
for {{ product.price | money }}<br />
</li><br />
{% endfor %}<br />
{% endif %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
<br />
In the <tt>{% if group.bundle %}…{% else %}…{% endif %}</tt> block we handle the special case of a group being a bundle. In this case we want to have a different link <tt><nowiki>{{ bundle.buy_link }}</nowiki></tt> that adds the bundled products to the basket. Also we want to show a message <tt><nowiki>{{ bundle.buy_text }}</nowiki></tt> that contains the price of the whole bundle. For more information on bundles see the [[Shopify_Liquid|Variable Reference]].<br />
<br />
== Stylized recommendations with CSS 3 animations ==<br />
<br />
The next example shows the real powers of customized templates in Directed Edge for Shopify. This example shows only the product images of the recommended products. If you hover over one of them a neat animation will enlarge that particular item and reveal a product's title, price and also the original price if the product is on sale.<br />
As you will see CSS-code can be directly embedded into the liquid template.<br />
<br />
Note hover that: '''JavaScript code will be stripped out before rendering'''.<br><br />
If you need to use JavaScript it has to be embedded in the Shopify templates. You can set a callback using <tt>{% assign directed-edge-callback = 'myJsFunction' %}</tt> before including the <tt>{% include 'directed-edge' %}</tt> snippet. Since you can set element ids and classes as you need you will be able to easily manipulate the elements later.<br />
<br />
<br />
<source lang="xml"><br />
<style type="text/css"><br />
.recommendations-label {<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
}<br />
<br />
.recommendation-group {<br />
float: left;<br />
display: block;<br />
clear: both;<br />
padding: 5px;<br />
}<br />
<br />
.recommended-item {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
border: 1px solid #ddd;<br />
border-radius: 3px;<br />
}<br />
<br />
.bundle-plus {<br />
display: inline-block;<br />
float: left;<br />
text-align: center;<br />
cursor: pointer;<br />
height: 102px;<br />
padding: 3px;<br />
margin: 3px;<br />
font-family: Arial, sans-serif;<br />
font-size: 2em;<br />
line-height:4em;<br />
vertical-align: middle;<br />
}<br />
<br />
.recommended-image-container {<br />
float: left;<br />
width: 102px;<br />
line-height: 100px;<br />
}<br />
<br />
.recommended-image-container img {<br />
vertical-align: top;<br />
}<br />
<br />
.recommended-details {<br />
width: 1px;<br />
height: 102px;<br />
float: left;<br />
overflow: clip;<br />
text-align: left;<br />
transition: width 0.2s;<br />
-webkit-transition: width 0.2s; /* Safari, Chrome */<br />
}<br />
<br />
<br />
.recommended-item:hover .recommended-details {<br />
width: 120px;<br />
}<br />
<br />
.rtitle, .rprice {<br />
margin-left: 1px;<br />
text-align: left;<br />
overflow: hidden;<br />
white-space: nowrap;<br />
text-overflow: ellipsis;<br />
}<br />
<br />
.sale-price {<br />
text-decoration: line-through;<br />
} <br />
</style><br />
<br />
<div class="recommendations"><br />
{% for group in groups %}<br />
<div class="recommendation-group"><br />
<span class="recommendations-label">{{ group.label }}</span><br />
<ul><br />
{% for product in group.products %}<br />
<a href="{{ product.url }}"><br />
<div class="recommended-item"><br />
<div class="recommended-image-container"><br />
<img src="{{ product.featured_image | product_img_url: 'small' }}" /><br />
</div><br />
<div class="recommended-details"><br />
<div class="rtitle"><br />
{{ product.title }}<br/><br />
{% if product.compare_at_price_min > product.price_min %}<br />
<span class="sale-price">{{ product.compare_at_price_min | money }}</span><br />
{% endif %}<br />
{{ product.price | money }}<br />
</div><br />
</div><br />
</div><br />
</a><br />
{% if group.bundle and product == group.products.first %}<br />
<div class="bundle-plus">+</div><br />
{% endif %}<br />
{% if group.bundle and product == group.products.last %}<br />
<div class="bundle-plus"><br />
<a href="{{ bundle.buy_link }}">{{ bundle.text }}</a><br />
</div><br />
{% endif %}<br />
{% endfor %}<br />
</ul><br />
</div><br />
{% endfor %}<br />
</div><br />
</source></div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=287Shopify Liquid2013-10-10T04:50:26Z<p>Scott: </p>
<hr />
<div>== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in our [http://shopify.directededge.com/settings#styling Appearance Settings].<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=286Shopify Liquid2013-10-10T04:37:30Z<p>Scott: </p>
<hr />
<div>== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. <tt>bundle</tt>, <tt>recommended_product</tt>, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=285Shopify Liquid2013-10-10T04:36:47Z<p>Scott: </p>
<hr />
<div>== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access extra information about bundles, not available in other groups:<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. It can be formatted with the price filter just like elsewhere in Shopify templates: <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will ask the user to pick a variant if multiple variants are available for the bundled products.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=284Shopify Liquid2013-10-10T02:57:40Z<p>Scott: </p>
<hr />
<div>== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product’s properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle’s buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=283Shopify Liquid2013-10-10T02:45:23Z<p>Scott: </p>
<hr />
<div>== Liquid variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=282Shopify Liquid2013-10-10T02:42:40Z<p>Scott: </p>
<hr />
<div>== Liquid Variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=281Shopify Liquid2013-10-10T02:27:28Z<p>Scott: </p>
<hr />
<div>== Liquid Variables supported by Directed Edge ==<br />
__TOC__<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=280Shopify Liquid2013-10-10T02:25:46Z<p>Scott: </p>
<hr />
<div>== Liquid Variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, “Recommended Items”, “Recently Viewed”, etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. “Buy both for $20”) which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=279Shopify Liquid2013-10-10T01:28:17Z<p>Scott: </p>
<hr />
<div>== Liquid Variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, "Recommended Items", "Recently Viewed", etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || An array of all of the products in returned for this recommendations group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. "Buy both for $20") which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scotthttps://developer.directededge.com/index.php?title=Shopify_Liquid&diff=278Shopify Liquid2013-10-10T01:27:21Z<p>Scott: </p>
<hr />
<div>== Liquid Variables supported by Directed Edge ==<br />
=== <tt>groups</tt> ===<br />
The liquid variable groups contain all recommendation types that are available for the requested page. Each group has following properties:<br />
{| class="variable-ref-table"<br />
|-<br />
| label || A formatted label of the group, for example, "Recommended Items", "Recently Viewed", etc. Those labels can be customized in the [http://shopify.directededge.com/settings#styling Directed Edge for Shopify Appearance Settings] page.<br />
|-<br />
| handle || A machine friendly identifier for the group (e.g. bundle, recommended_product, etc.)<br />
|-<br />
| products || A list of products that are recommended for this group.<br />
The following example would print title and price of all products in all available groups:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
<ul><br />
{% for product in group.products %}<br />
<li><br />
<b>{{ product.title }}</b><br /><br />
{{ product.price | money }}<br />
{% endfor %}<br />
</ul><br />
{% endfor %}<br />
</source><br />
A detailed description of all product's properties can be found [http://docs.shopify.com/themes/liquid-variables/product here].<br />
|-<br />
| bundle || A boolean field that indicates if this group is a bundle. This is useful to render custom content for that particular group. The following snippet would display both product images separated by a plus sign and followed by a equals sign and the bundle price:<br />
<source lang="xml"><br />
{% for group in groups %}<br />
{% if group.bundle %}<br />
{{ group.products.first.featured_image | product_img_url: 'small' }}<br />
+<br />
{{ group.products.last.featured_image | product_img_url: 'small' }}<br />
=<br />
{{ bundle.price }}<br />
{% else %}<br />
<!-- render other content here --><br />
{% endif %}<br />
{% endfor %}<br />
</source><br />
|}<br />
<br />
=== <tt>bundle</tt> ===<br />
The bundle variable is used to access supplementary information about bundles<br />
{| class="variable-ref-table"<br />
|-<br />
| text || Bundle's buy message (e.g. "Buy both for $20") which can be adjusted in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page.<br />
|-<br />
| price || The total price of a bundle calculated using the method specified in the [http://shopify.directededge.com/settings#bundle Directed Edge for Shopify Bundle Settings] page. As any price it can be formatted with the price filter (e.g. <source lang="xml">{{ bundle.price | money }}</source><br />
|-<br />
| buy_link || A link that will add both products to the shopping cart and will present the user a product variant chooser if necessary.<br />
|}</div>Scott