Everyfeed API Documentation

REST-ful API to Skimlinks Everyfeed.

For the impatient, a full call with an API key abcedf0123456789abcedf looks like: http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/adidas/price1/25/price2/50/currency/GBP

API endpoint

Everyfeed API supports xml and json which makes it easy to use in any language. You will need an API_KEY to use the API. If you don't have one, you can get your API key here. Depending on your choice of language, your API call should begin with one of:

XML

http://api.everyfeed.net/xml/API_KEY/

Returns data in XML.

JSON

http://api.everyfeed.net/json/API_KEY/

Returns data as a Json encoded object.

Top

Simple calls

The API is designed in a key-value fashion. All values should be url encoded. For instance, if you are searching for all products under the category "Home & Garden", the phrase "Home & Garden" should be encoded to %22Home+%26+Garden%22 Most languages have library functions to do this. Some are mentioned below:

PHP

PHP provides the urlencode() function.

Javascript

Please do not use the escape() function. It does not escape the following characters * @ - _ + . /. Instead, use this:

function my_escape(str) {
	return escape(str).replace('/', '%2F');
}

Python

Python 2.6+ provides the urllib.quote_plus() function.

Top

Search queries

Standard search query

This is the most basic query that returns products which match SEARCH_TERM. The matching is done on the title, description, manufacturer, by and merchant name.

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM

As an example, searching for wall bracket will look like

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/wall+bracket

Number of results

By default the api call returns 10 results. To change this you need to add two extra terms, start and rows. Start refers to the page number to display. Rows refers to the number of search results on each page. The API returns a maximum of 500 results at a time. Any number > 100 returns 100 results.

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM/start/START_NO/rows/ROW_NO

As an example, searching for the first 20 results for red dress will look like

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/red+dress/start/0/rows/20

Row count starts at 0 so this returns rows 0-19

Whereas searching for the next 20 results will look like the following

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/red+dress/start/1/rows/20

This will return rows 20-39

Date range

This query lets you search between two date ranges. Either parameter can be omitted.

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM/date1/YYYY-MM-DD/date2/YYYY-MM-DD

A search for an ipod first seen between May 01, 2010 and June 01, 2010 would look like

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/ipod/date1/2010-05-01/date2/2010-06-01

Please note that date1 < date2.

If you want to search from a certain date to today use date1.

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/ipod/date1/2010-05-01

If you want to search from all time to a certain date use date2

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/ipod/date2/2010-05-01

Price range

This query lets you search between two price points. Either parameter can be omitted.

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM/price1/PRICE1/price2/PRICE2/currency/CURRENCY

A search for t-shirts priced less than 20.00 GBP,

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/t-shirt/price2/2000/currency/GBP

Valid currencies are GBP, USD, EUR

Please note: Prices must be entered in full without the decimal point. For example 20.99 must be written as 2099.

Category search

This query lets you search for products within a category. To search multiple categories, separate them by comma (,).

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM/category/CATEGORY

A search for all products under the category Clothing will look like

http://api.everyfeed.net/xml/abcedf0123456789abcedf/category/Clothing

while a search for spade under Home & Garden and Garden & Outdoors would look like

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/spade/category/%22Home+%26+Garden%22,%22Garden+%26+Outdoors%22

Note the quotes (%22) around Category names.

You can also do the same search by category_id like so:

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/spade/category_id/953,903

Top

Fetching

Fetching category list

http://api.everyfeed.net/xml/API_KEY/getmeta/category/

This returns a flat category structure. The count field denotes the number of products under that category

Category Hierarchy

http://api.everyfeed.net/xml/API_KEY/getmeta/categorytree/

Returns a hierarchial list of names and the ids for each category.

Fetching merchants list

http://api.everyfeed.net/xml/API_KEY/getmeta/merchant/

Note: getmeta/merchant/ calls returns all merchants that we have product information available for, for all merchants the Skimlinks works with use the Merchant Method.

Note: getmeta calls supersede regular search queries and do not stack.

Sorting

The sort parameter lets you sort your results by relevance(default), price and firstseen.

http://api.everyfeed.net/xml/API_KEY/search/SEARCH_TERM/sort/SORT_BY

To sort in ascending order by price use,

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/cuff+links/sort/price

To sort in descending order use the -sort parameter instead,

http://api.everyfeed.net/xml/abcedf0123456789abcedf/search/cuff+links/-sort/price

Top

Code samples

JSON objects can be handled very elegantly in PHP and Python. The example code below shows you how easy it is to integrate the EveryFeed into your web application.

Python

#!/usr/bin/env python
import urllib
import urllib2
import simplejson

class FeedReader:
    baseurl = 'http://api.everyfeed.net/json/abcdef0123456789abcdef'
    def getResults(self, searchTerm):
        url = '%s/search/%s' % (self.baseurl, urllib.quote_plus(searchTerm))
        conn = urllib2.urlopen(url)
        data = conn.read()
        conn.close()
        return simplejson.loads(data)

if __name__ == '__main__':
    result = FeedReader().getResults('purse')
    print 'Num of results:', result['skimFeed']['numFound']
    for doc in result['skimFeed']['products']:
        print doc['title'], doc['price']

PHP

<?php
class FeedReader {
    var $baseurl = 'http://api.everyfeed.net/json/abcdef0123456789abcdef';
    function getResults($searchTerm){
        $searchTerm = urlencode($searchTerm);
        $data = file_get_contents($this->$baseurl . "/search/$searchTerm");
        $result = json_decode($data);
        if (json_last_error() != JSON_ERROR_NONE) {
            return "Error";
        }
        return $result;
    }
}

$f = new FeedReader();
$result = $f->getResults('adidas');
print "Num Found:" . $result->skimFeed->numFound . "\n";
foreach($result->skimFeed->products as $doc) {
    print $doc->title . "\n";
}
?>

Top

Output format

XML

A typical xml feed looks like

<skimFeed version="2">
  <numFound>25491</numFound>
  <products>
    <product id="12808|48988923">
      <title>Big & Tall Charcoal Stripe Regular Suit Jacket</title>
      <url>http://www.burton.co.uk/webapp/wcs/stores/servlet/ProductDisplay?catalogId=33052&storeId=12551&categoryId=209307&parent_category_rn=208982&productId=1305237&langId=-1&cmpId=616</url>
      <image_url>http://media.burton.co.uk/wcsstore/Burton/images/catalog/02E15VGRY_normal.jpg</image_url>
      <verified_image>True</verified_image>
      <currency>GBP</currency>
      <price>6900</price>
      <prev_price>6995</prev_price>
      <firstseen>2010-04-22T19:45:59Z</firstseen>
      <lastseen>2010-06-05T04:43:52Z</lastseen>
      <merchant id="12808">Burton</merchant>
      <by></by>
      <manufacturer>Burton</manufacturer>
      <description>Single breasted 2 button charcoal stripe suit jacket in a regular fit. Includes double vents.</description>
      <category>
      	<item id="137">Suits</item>
        <item id="100">Men</item>
        <item id="2">Clothing</item>
        <item id="1">Clothing, shoes & accessories</item>
      </category>
    </product>
  </products>
</skimFeed>

numFound: Total number of results found for this search query
product: Encloses a product. The id is unique for that product.
title: Contains the merchant specified title.
description: Merchant specified description of the product.
url: The url to the product page. Please note that this url "clean" and not affiliatized. You will need to have Skimlinks installed on your site to monetize it.
image_url: The url to the image of the product.
price: The current price of this product. This is the latest price that we have on our system and may differ from the actual price on the page.
prev_price: The previous price of this product.
currency: The currency in which the price has been quoted.
firstseen: The date this product was first seen by our system. This can be used to filter new products.
lastseen: The date this product was last seen by our system. This can be used to filter recently updated products.
merchant: The name of the merchant. The id uniquely identifies a merchant.
by: Brand for a product, Author for a book. May be empty.
manufacturer: Contains the manufacturer of a product where available, or the Publisher of a book.
category: Skimlinks normalized categories here. Not all products have categories, but we are getting there.

Top

Merchant API

Note: This Method returns all merchants that Skimlinks works with. To return only the merchants that we have product information available for please use the getmeta/merchant/ call documented under fetching merchants list.

search: Search keyword
country: Name of the country (url encoded)
category: Category ID
limit: Results per page
start: Start from

XML

Domain list

http://api.everyfeed.net/merchants/xml/abcedf0123456789abcedf/domains/limit/2/start/0

Category list

http://api.everyfeed.net/merchants/xml/abcedf0123456789abcedf/category/1

Search (search parameter reqired)

http://api.everyfeed.net/merchants/xml/abcedf0123456789abcedf/search/bestbuy/country/united+states/category/8/limit/2/start/0

JSON

Domain list

http://api.everyfeed.net/merchants/json/abcedf0123456789abcedf/domains/limit/2/start/0

Category list

http://api.everyfeed.net/merchants/json/abcedf0123456789abcedf/category/1

Search (search parameter reqired)

http://api.everyfeed.net/merchants/json/abcedf0123456789abcedf/search/bestbuy/country/united+states/category/8/limit/2/start/0

PHPS

Domain list

http://api.everyfeed.net/merchants/phps/abcedf0123456789abcedf/domains/limit/2/start/0

Category list

http://api.everyfeed.net/merchants/phps/abcedf0123456789abcedf/category/1

Search (search parameter reqired)

http://api.everyfeed.net/merchants/phps/abcedf0123456789abcedf/search/bestbuy/country/united+states/category/8/limit/2/start/0

Top