Developers!

Let's say you want to display the score of any web site from SimpleOrNot.com on your web site. This API attempts to make this an easy process.

Right now, anyone may consume the SimpleOrNot API without an API key.

Usage: XML

To obtain all available data about a site in XML, run this call:

http://www.simpleornot.com/api.xml?site=digg-com&from=mysite.com

Sample data returned in XML:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
   <score type="integer">87</score>
   <thumbnail-image-medium>http://sono.s3.amazonaws.com/digg-com/medium.jpg</thumbnail-image-medium>
   <link>digg.com</link>
   <format>xml</format>
   <result>success</result>
   <thumbnail-image-small>http://sono.s3.amazonaws.com/digg-com/small.jpg</thumbnail-image-small>
   <has-thumbnail type="boolean">true</has-thumbnail>
   <comments-count type="integer">7</comments-count>
   <name>Digg</name>
   <profile>http://www.simpleornot.com/digg-com</profile>
</hash>

Usage: JSON

To obtain all available data about a site in JSON, run this call:

http://www.simpleornot.com/api.json?site=digg-com&from=mysite.com

Sample data returned in JSON:

{
  "score":87,
  "thumbnail_image_medium":"http://sono.s3.amazonaws.com/digg-com/digg-com/medium.jpg",
  "link":"digg.com",
  "format":"json",
  "result":"success",
  "thumbnail_image_small":"http://sono.s3.amazonaws.com/digg-com/small.jpg",
  "has_thumbnail":true,
  "comments_count":7,
  "name":"Digg",
  "profile":"http://www.simpleornot.com/digg-com"
}

Parameters in your API call

  • site - the site you're looking for in a parameterized format (ie "digg-com", note: don't include "www" or "http" and change periods to dashes)
  • from - your web site domain (we're not enforcing any rules here for now, but please let us know who you are!)

Typical usage pattern

  1. Fire a remote API call using one of the above URLs
  2. Check "result" for success or fail
  3. If "result" returns fail, look at "reason" and handle the error properly
  4. If "result" returns success, use whatever returned data you need

Returned data

The following data is returned from the call made above:

  • score - the site's Simple Score, or the site's mean rating
  • thumbnail-image-medium - medium-sized web site thumbnail (320x240px JPG)
  • link - direct link to the web site
  • format - format of the data returned (always "xml" or "json")
  • result - whether the API call was successful (always "success" or "fail")
  • reason - an error code indicating why a site wasn't found
  • thumbnail-image-small - small-sized web site thumbnail (200x150px JPG)
  • has-thumbnail - whether the site has a thumbnail available (always "true" or "false")
  • comments-count - the number of total ratings given on the site, including those without full-text reviews
  • name - the proper name of the web site
  • profile - direct link to the web site's profile on SimpleOrNot.com

Handling errors

"Result" always returns "fail" and an additional "reason" field is returned when there are errors. There are two possible error messages:

  • missing_from_param - this is displayed when you do not include a "from" parameter, indicating which site is making the API call (instead of registering for an API key, just include this with every API call you make)
  • site_not_found - this means the requested site wasn't found. The main reason this will happen is because you formatted the site incorrectly, or we don't have the site. You can test it by entering the site's parameterized URL, for example: http://www.simpleornot.com/digg-com