Hunch API

• For requests including the public_devKey, an unlimited number of your users can query our API, but each user is limited to 1000 requests per day per IP address.
• For requests including your secret devKey, you are limited to 5000 requests per day per devKey.
  Contact us to increase this limit at api@hunch.com.
• For requests not including a devKey, the limit is 50 requests per day per IP address. We recommend you only do this for testing purposes.

x

{"question": {"id": 425553,
              "text": "Alien abductions.  Are they:",
              "imageUrl": "http://hunch.com/media/img/s/R/o/g/Rog-3028823.jpg",
              "responseIds": [1537163, 1537153], 
              "topicId": "THAY"} }

x

{"response": {"id": 1537153,
              "text": "Real",
              "order": 1,
              "questionId": 425553,
              "topicId": "THAY"} }

x

{"result": {"id": 218,
            "name": "Apple MacBook Air",
            "type": "laptop",
            "urlName": "apple-macbook-air",
            "description": "With the MacBook Air, Apple has created...",
            "imageUrl": "http://hunch.com/media/img/s/a/p/p/apple-macbook-air-2889683._f100_100.jpg",
            "readMoreUrl": "http://www.apple.com/macbookair/",
            "hunchUrl": "http://hunch.com/laptops/result/apple-macbook-air/218/",
            "topicId": 2 } }

console-video-games

http://hunch.com/console-video-games/

x

{"topic": {"id": 3,
           "decision": "Where should I go on vacation?", 
           "urlName": "vacations", 
           "shortName": "Vacations", 
           "hunchUrl": "http://hunch.com/vacations/",
           "imageUrl": "http://hunch.com/media/img/s/v/L/H/vLH-3242833._f100_100.jpg", 
           "resultType": "destination", 
           "eitherOrTopic": 0,
           "category": { "categoryUrlName": "entertainment-media", 
                         "categoryName": "Entertainment & Media",
                         "categoryImageUrl": "http://hunch.com/media/img/categories/Book_Movies.gif" } } }

{"topics": [ { "id": "16063", 
               "decision": "Should I sell my car?",
               "urlName": "sell-my-car",
               "score": 5.643917 },
             { "id": "114",
               "decision": "Should I buy or lease a car?",
               "urlName": "should-i-buy-or-lease-a-car", 
               "score": 5.625218 } ] }

{"results": [ { "id": "217533", 
                "name": "Tesla Roadster",
                "urlName": "tesla-roadster", 
                "score": 12.990862 },
              { "id": "1801683", 
                "name": "Tesla Model S",
                "urlName": "tesla-model-s", 
                "score": 9.0936030 } ] }

{ "questions": [{ "id": 419753, 
                  "questionText": "Do you believe in UFOs or alien visits to Earth?",                  
                  "answers": ["No", "Yes"] },
         
                { "id": 425553, 
                  "questionText": "Alien abductions.  Are they:",
                  "answers": ["Fake", "Real"] }] }

{"categories": [ {"urlName": "autos", 
                  "name": "Autos"
                  "imageUrl": "http://hunch.com/media/img/categories/Auto.gif"}, 
                 {"urlName": "beauty-personal-care", 
                  "name": "Beauty & Personal Care",
                  "imageUrl": "http://hunch.com/media/img/categories/Beauty_style.gif"}, 
                 ...
                 {"urlName": "culture-humanities", 
                  "name": "Culture & Humanities",
                  "imageUrl": "http://hunch.com/media/img/categories/Lifestyle.gif"} ] }

x

{"topics": [ { "id": 53,
               "decision": "Which broadway show should I see?", 
               "imageUrl": "http://hunch.com/media/img/s/w/i/c/wicked-1122623._f100_100.jpg", 
               "resultType": "show", 
               "urlName": "broadway-shows", 
               "shortName": "Broadway Shows", 
               "eitherOrTopic": 0 },
             ...
             { "id": 87,
               "decision": "Which foreign language should I learn?", 
               "imageUrl": "http://hunch.com/media/img/s/f/r/e/french-4491._f100_100.png", 
               "resultType": "language", 
               "urlName": "which-foreign-language-should-i-learn", 
               "shortName": "Foreign Languages", 
               "eitherOrTopic": 0 } ] }

x

{"topics": [ { "id": 53,
               "decision": "Which broadway show should I see?", 
               "imageUrl": "http://hunch.com/media/img/s/w/i/c/wicked-1122623._f100_100.jpg", 
               "resultType": "show", 
               "urlName": "broadway-shows", 
               "shortName": "Broadway Shows", 
               "eitherOrTopic": 0 },
             ...
             { "id": 87,
               "decision": "Which foreign language should I learn?", 
               "imageUrl": "http://hunch.com/media/img/s/f/r/e/french-4491._f100_100.png", 
               "resultType": "language", 
               "urlName": "which-foreign-language-should-i-learn", 
               "shortName": "Foreign Languages", 
               "eitherOrTopic": 0 } ] }

x

{"topics": [ { "id": 53,
               "decision": "Which broadway show should I see?", 
               "imageUrl": "http://hunch.com/media/img/s/w/i/c/wicked-1122623._f100_100.jpg", 
               "resultType": "show", 
               "urlName": "broadway-shows", 
               "shortName": "Broadway Shows", 
               "eitherOrTopic": 0 },
             ...
             { "id": 87,
               "decision": "Which foreign language should I learn?", 
               "imageUrl": "http://hunch.com/media/img/s/f/r/e/french-4491._f100_100.png", 
               "resultType": "language", 
               "urlName": "which-foreign-language-should-i-learn", 
               "shortName": "Foreign Languages", 
               "eitherOrTopic": 0 } ] }

{ "sampleMean": 0.54580801944106927,
  "sampleVariance": 0.2479618834067473,
  "sampleStdDev": 0.49795771246838549,
  "standardError": 0.0077626059967443872,
  "confidenceInterval": 0.015214707753618998,
  "sampleSize": 4115 }

{ "sampleMean1": 0.54753431621759019,
  "sampleMean2": 0.069649211997966448
  "sampleVariance1": 0.24780347898992308,
  "sampleVariance2": 0.064814674780713039,
  "sampleStdDev1": 0.49779863297313609,
  "sampleStdDev2": 0.25458726358699296,
  "covariance": -0.0005147222587387906,
  "correlationRho": -0.0040614637056410529,
  "sampleSize": 3934 }

{ "correlations": [[1790324, 0.40824829046386302],
                   [1789044, 0.35634832254989918],
                   [1523833, 0.35169521481684363],
                   [1532633, 0.32513018339366734],
                   [253581,  0.31082489959181037]] }

{ "correlations": [[1790314, -0.40824829046386302],
                   [1789054, -0.35634832254989941],
                   [1523843, -0.35169521481684363],
                   [1445993, -0.32761525463309382],
                   [1532643, -0.32513018339366734]] }

{ "similarItemIds": [219, 792143, 908453, 2087263, 2367223] }

{ "predictedResponseIds": [1532633, 1445983, 1386554, 253581, 1645064] }

{ "predictedResultIds": [218, 219, 2102564, 649, ... 1114353, 528214, 528224] }

x

x

x

{"nextQuestion": { "questionId": 8, 
                   "questionNumber": 1, 
                   "questionText": "On which game console will you be playing this game?",
                   "responses": [ { "responseId": 22,
                                    "responseText": "Wii",
                                    "qaState": "22" }, 
                                  { "responseId": 23, 
                                    "responseText": "Xbox 360", 
                                    "qaState": "23" }, 
                                  { "responseId": 24,
                                    "responseText": "Playstation 3", 
                                    "qaState": "24" }, 
                                  { "responseText": "Skip this question", 
                                    "qaState": "-8" } ] },
 "prevQaState": "",
 "topic": { "topicId": 1, 
            "topicDecision": "Which console video game is right for me?", 
            "hunchUrl": "http://hunch.com/console-video-games/", 
            "imageUrl": "http://hunch.com/media/img/s/o/r/a/orange-box-the-xbox-360-1697943._f160_160.jpg",
            "category": { "categoryUrlName": "entertainment-media",
                          "categoryName": "Entertainment & Media",
                          "categoryImageUrl": "http://hunch.com/media/img/categories/Book_Movies.gif" } },
 "rankedResultResponses": "" }

{"rankedResultResponses": "1388654.1738583.18.37.25.1787423.1657443.1801463.15.1597154"}

{"rankedResultIds": [ 1788223, 527854, 1894974, 527864, 1057433, ... 2023413, 2039163, 2054283 ],
 "wildCardResultId": 2023413,
 "hunchUrl": "http://hunch.com/console-video-games/all/" }

1. Register your application with Hunch, and you will receive an appKey, which is safe to let others see (unlike your devKey).
2. When a user wishes to sign into your application, ask for their username, and make a call to getAuthToken with your appKey and their username. Your app will get back an authToken and a URL.
3. Direct the user to the URL in a web browser. The user will need to sign in if they aren't already. Once at that URL, the user can Accept or Reject your authToken request.
4. Pass the authToken to any API call that will accept it (some will require it), and your app will be making the call on the authenticated user's behalf. If the authToken is not yet accepted by the user, the call will return as if no authToken argument was given. Your app can call getAuthStatus to determine if the authToken has been accepted or not.

{"authToken": "55c085ccfeac249547de08744eab4e244d81c258", 
 "verifyUrl": "http://hunch.com/authorize/?avrjo"}

{"status": "accepted"}

POST /api/teachHunchAboutYou/ HTTP/1.1
Host: api.hunch.com
Content-Length: 68
Content-Type: application/x-www-form-urlencoded

questionId=212&responseId=109&authToken=55c085ccfeac249547de08744eab

x

x

{ "storedResponseId": 109,
  "nextQuestion" : { "questionId": 729234,
                     "questionText": "Are you afraid of the dark?",
                     "responses": [ {"responseId": 2576074,
                                     "responseText": "Yes"},
                                    {"responseId": 2576084,
                                     "responseText": "No"},
                                    {"responseId": -729234, 
                                     "responseText": "Skip this question"} ] },
  "percentWithSameAnswer": 44 }

POST /api/trainResult/ HTTP/1.1
Host: api.hunch.com
Content-Length: 86
Content-Type: application/x-www-form-urlencoded

resultId=218&responses=729234.200.1168&rating=1&authToken=55c085ccfeac249547de08744eab

{ "trainingRecorded": true }

hunch.nextQuestion( "", 25, "160x160", "100x100", "36x36", 
                    function (response) {
                         alert(response["nextQuestion"]["questionText"]);
                    });

hunch.rankedResults( "1388654.1738583.18.37.25.1787423.1657443.1801463.15.1597154", 1, 
                     function (response) {
                          alert(response["rankedResultIds"]);
                     });

hunch.getResult( 1788223, "125x150", 
                 function (response) {
                      alert(response["result"]["name"]);
                 });

hunch.getQuestion( 425553, "160x160", 
                   function (response) {
                        alert(response["question"]["text"]);
                   });

hunch.getResponse( 1537153, "100x100", 
                   function (response) {
                        alert(response["response"]["text"]);
                   });

hunch.getTopic( "vacations", "36x36",
                function (response) {
                     alert(response["topic"]["decision"]);
                });

hunch.searchForTopic( "cars", 
                      function (response) {
                           alert(response["topics"][0]["decision"]);
                      });

hunch.searchForResult( "tesla", 25, 
                       function (response) {
                            alert(response["results"][0]["name"]);
                       });

hunch.searchForQuestion( "aliens+ufos", 
                         function (response) {
                              alert(response["questions"][0]["questionText"]);
                         });

hunch.listCategories( function (response) {
                           alert(response["categories"][0]["name"]);
                      });

hunch.listTopics( "culture-humanities", 
                  function (response) {
                       alert(response["topics"][0]["decision"]);
                  });

hunch.authenticateUser( "http://hunch.com/developers/" );

hunch.responseStats( 109, 
                     function (response) {
                          alert(response["sampleMean"]);
                     });

hunch.responsePositiveCorrelations( 109, 5,
                                    function (response) {
                                         alert(response["correlations"][0]);
                                    });

hunch.responseNegativeCorrelations( 109, 5,
                                    function (response) {
                                         alert(response["correlations"][0]);
                                    });

hunch.responsePairStats( 109, 113,
                         function (response) {
                              alert(response["correlationRho"]);
                         });