The Spendabit Search API

The Spendabit Search API is a simple, JSON-based interface to the Spendabit search engine. All calls to the API are made via the following API Endpoint (base URL):

https://spendabit.co/api/v0/go

If you're adventurous you can effectively “discover” all the functionality of the API by observing the functionality of the standard, HTML-based interface, as accessible from our homepage — almost all query variables share the same names and accept the same values. But if you prefer it by the book, read on. :-)

Basic Searching

Every request to the Spendabit Search API must include the query-variable q, specifying the keyword(s) which the client wishes to match on. For example, to search for all products matching the keyword chocolate, you would issue an HTTP GET request to the following URL:

https://spendabit.co/api/v0/go?q=chocolate

Below is a hypothetical JSON-formatted result-set:

{
  "products": [{
      "name": "Spicy Hot Chocolate",
      "merchantName": "Square Market",
      "url": "https://spendabit.co/product/squaremarket/spicy-hot-chocolate?q=chocolate",
      "thumbnailURL": "https://d2isyty7gbnm74.cloudfront.net/5WUzQvBvbarJBPiWWAhNXUtP8II=/276x276/square-production.s3.amazonaws.com/files/863d0fc21ea43950ed9e0e1d58ce24e1d7a5895a/original.jpeg",
      "priceAsString": "$1.50",
      "priceUSD": 1.5
  }, {
      "name": "INSTEN Anti-glare Screen Protector for LG Chocolate Touch VX8575",
      "merchantName": "Overstock.com",
      "url": "https://spendabit.co/product/overstock/6580708?q=chocolate",
      "thumbnailURL": "http://cdn.overstock.com/images/products/6580708/79/172/BasAcc-Anti-Glare-Screen-Protector-for-LG-Chocolate-Touch-VX8575-P14155318.jpg",
      "priceAsString": "$1.49",
      "priceUSD": 1.49
  }]
}

Navigating Result Pages

Assuming a query returns more than 60 results, you can “paginate” using the query-variable offset, specifying a multiple of 60 (our default page-size) as the value (e.g. 60, 120, 180, etc). For example, to access page three of the products matching the keyword chocolate, you would issue an HTTP GET request to the following URL:

https://spendabit.co/api/v0/go?q=chocolate&offset=180

Filtering Results

The Spendabit Search API presently supports filtering products by merchant and by price. Both of these are outlined below.

Each JSON response-object includes, alongside the array of products a set of filterOptions. The structure of this field looks something like the following:

"filterOptions": [
  { "type": "price",
    "options": [
      { "label": "$0.01 – $32.99", "labelAbbr": "$0.01 – $32.99",
        "queryVar": "price", "value": "0.01-32.99",
        "url": "https://spendabit.co/api/v0/go?q=jacket&price=0.01-32.99" },
      { "label": "$33.39 – $49.99", "labelAbbr": "$33.39 – $49.99",
        "queryVar": "price", "value": "33.39-49.99",
        "url": "https://spendabit.co/api/v0/go?q=jacket&price=33.39-49.99" },
      { "label":"$49.99 – $94.99", "labelAbbr": "$49.99 – $94.99",
        "queryVar":"price", "value":"49.99-94.99",
        "url":"https://spendabit.co/api/v0/go?q=jacket&price=49.99-94.99" },
      { "label": "$94.99 – $150,000", "labelAbbr": "$94.99 – $150,000",
        "queryVar": "price", "value": "94.99-150000.00",
        "url": "https://spendabit.co/api/v0/go?q=jacket&price=94.99-150000.00" }
    ]
  },
  { "type": "merchant",
    "options": [
      { "label": "DinoDirect", "labelAbbr": "DinoDirect",
        "queryVar": "merchant", "value": "dinodirect",
        "url": "https://spendabit.co/api/v0/go?q=jacket&merchant=dinodirect" },
      { "label": "Newegg", "labelAbbr": "Newegg",
        "queryVar": "merchant", "value": "newegg",
        "url": "https://spendabit.co/api/v0/go?q=jacket&merchant=newegg" },
      { "label": "Survival Camping Store", "labelAbbr": "Survival Camping ...",
        "queryVar": "merchant", "value": "survivalcampingstore",
        "url": "https://spendabit.co/api/v0/go?q=jacket&merchant=survivalcampingstore" }
    ]
  }
]

Assuming you have a parsed JSON object (in variable r), you could access the filter-by-merchant options like this:

opts = r.filterOptions.filter(
  function(e) { return e.type == 'merchant'; }
)[0].options
      

Then you could, for example, construct a string naming all the merchants like this:

opts.map(function(o) { return o.label; }).join(', ');

Each option also contains a url to save you the trouble of constructing one yourself. E.g., opts[1].url might give you something like this:

https://spendabit.co/api/v0/go?q=whatever&merchant=overstock

Filtering by Price

Filtering results by price is done via the query-variable price. Specify a price-range using a low value and a high, value separated by a hyphen, and in terms of dollars (USD). For example, to see all products matching the keyword chocolate that cost less than 50 dollars, use the following URL:

https://spendabit.co/api/v0/go?q=chocolate&price=0.00-50.00

Filtering by Merchant

You also have the option of filtering results by merchant. This is done using the query-variable merchant, specifying the ID of the merchant in question. For example, to see all products matching chocolate for the merchant with the ID bitcoffee, the following URL would be used:

https://spendabit.co/api/v0/go?q=chocolate&merchant=bitcoffee

You can also filter on multiple merchants at once. For example the following URL would additionally give back results for merchant store.bitcoin.com:

https://spendabit.co/api/v0/go?q=chocolate&merchant=bitcoffee&merchant=store.bitcoin.com

Avoiding Cross-Domain Request Issues

If you want to process data returned by the API directly in the web-browser using JavaScript, then you'll likely have to work around browser enforcement of the same-origin policy. This can be done by passing an extra callback parameter when making API calls, so the result is returned as “JSON-P”.