API Documentation

Merchants API

The Merchants API is the main interface for publishers wishing to know statistics about the merchants on our network. The Merchants API returns all merchants that Skimlinks works with. All values should be url encoded. For instance, if you are searching for "Best Buy", the phrase "Best Buy" should be encoded to Best%20Buy.

Changelog


0.3

2012-03-06 - Merchants and Product (EveryFeed) are now separate APIs.

0.4

2012-09-11 - Add Categories to 'search' call

API Endpoint

The Merchant API endpoint is:

http://api-merchants.skimlinks.com/merchants/

API Methods

The Merchants API consists of the following methods:

Get category information (/categories)

Retrieve a list of our Merchant categories. Use in conjunction with the /category call to get a list of the merchants in a specific category.

Endpoint

http://api-merchants.skimlinks.com/merchants/categories
Fields Description
key

required

Public API key - char(32)

format

required

The format of the returned results, either xml or json.

Example API Call / Response

XML
JSON

GET

Example Call

Returns all category information including the IDs. Any child categories are listed in a `children` element.

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/categories

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksCategories>
    <category>
        <id>1</id>
        <name>adult &amp; mature</name>
    </category>
    <category>
        <id>2</id>
        <name>arts, crafts &amp; hobbies</name>
    </category>
    <category>
        <id>3</id>
        <name>automotive, cars &amp; bikes</name>
    </category>
    <category>
        <id>4</id>
        <name>baby &amp; parenting supplies</name>
    </category>
    <category>
        <id>5</id>
        <name>books &amp; magazines</name>
    </category>
<skimlinksCategories>

              

Get Merchant Domain Information (/domains)

Retrieve a list of domains for the Merchants we work with.

Endpoint

http://api-merchants.skimlinks.com/merchants/domains
Fields Description
key

required

Public API key - char(32)

format

required

The format of the returned results, either xml or json

start

optional

The index from which to start returning results. (defaults to 0) - int

limit

optional

Number of results to return - int

Example API Call / Response

XML
JSON

GET

Example Call

Return 1 merchant domain, starting from the 100th domain.

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/domains/limit/1/start/100

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksMerchantsDomains version="0.4">
  <timeStamp>2012-03-12T15:36:49+00:00</timeStamp>
  <numFound>23094</numFound>
  <numStarted>100</numStarted>
  <numReturned>1</numReturned>
  <domains>
    <domain id="23380">neogie.com</domain>
  </domains>
</skimlinksMerchantsDomains>

              

This method returns information about merchants and categories that match the supplied search term. The search term is matched against merchant name and domain, and category name.

Endpoint

http://api-merchants.skimlinks.com/merchants/search
Fields Description
search

required

The merchant to search for - string

key

required

Public API key - char(32)

format

required

The format of the returned results, either xml or json

start

optional

The index from which to start returning results. (defaults to 0) - int

limit

optional

Number of results to return - int

filter_by

optional

Set to preferred to only return merchants who are part of the Skimlinks Preferred Partner Program. Should be set as a query param e.g. ?filter_by=preferred

Example API Call / Response

GET

Example Call

Searching for the word 'Con' limiting the result set to two.

XML Response

Get Merchant Category Information (/category)

Returns information about merchants in a particular category. Use in conjunction with the /categories call to get a list of the Category IDs to use with /category call.

Endpoint

http://api-merchants.skimlinks.com/merchants/category
Fields Description
key

required

Public API key - char(32)

format

required

The format of the returned results, either xml or json

start

optional

The index from which to start returning results. (defaults to 0) - int

limit

optional

Number of results to return - int

filter_by

optional

Set to preferred to only return merchants who are part of the Skimlinks Preferred Partner Program. Should be set as a query param e.g. ?filter_by=preferred

Example API Call / Response

XML
JSON

GET

Example Call

Return the first merchant in the category 'Arts, Crafts & Hobbies'

http://api-merchants.skimlinks.com/merchants/xml/aabbccddeeffgghhiijjkk1122334455/category/2/limit/1

XML Response

<?xml version="1.0" encoding="UTF-8"?>
<skimlinksMerchants version="0.4">
  <timeStamp>2012-03-12T15:20:52+00:00</timeStamp>
  <numFound>313</numFound>
  <numStarted>0</numStarted>
  <numReturned>1</numReturned>
  <merchants>
    <merchant>
      <dateUpdated>2012-03-11T00:02:00+00:00</dateUpdated>
      <merchantID>17751</merchantID>
      <merchantName>123Posters.com, Inc.</merchantName>
      <averageConversionRate>0</averageConversionRate>
      <averageCommission>0</averageCommission>
      <logo>
        http://skimlinks.com/images/merchantlogos/17751.jpg
      </logo>
      <domains>
      <domains>
        <domain>
        <domainID>9695</domainID>
        <domainName>123posters.com</domainName>
        </domain>
      </domains>
      <categories>
        <category id="10">consumer electronics;cameras &amp; photos</category>
        <category id="8">consumer electronics</category>
        <category id="47">music, mp3 &amp; movies</category>
        <category id="2">arts, crafts &amp; hobbies</category>
      </categories>
      <countries>
        <country>united states</country>
      </countries>
    </merchant>
  </merchants>
</skimlinksMerchants>