API Reference

Usage


HTTP Encoding

API calls are made over an HTTP connection using either GET or POST requests. Returned values are JSON encoded.

The base URL for requests is http://api.hunch.com/api/v1/. For example, the get-recommendations call has the URL http://api.hunch.com/api/v1/get-recommendations/.

Parameters passed in to each call must be URL-encoded. Any data being written should be sent via POST but GETs are accepted to make testing with a browser easier.

On input, lists should be comma-delimited, for example topic_ids=list_magazine,list_movie. booleans should be passed as one of 0, 1, t, f, true, false, True, False, YES, or NO.

HTTP response codes have their usual meaning: 404 means a named resource was not found, 200 means a succesful response was returned, 401 means authorization failed, etc.

If a callback parameter is passed, then JSONP is used, returning text/javascript instead of the usual application/json.

If the boolean suppress_http_errors is true, then even error responses will have a HTTP response code of 200. This can be useful for JSONP and certain libraries such as jQuery. The JSON of the responses will still identify them as errors, as described below.

Error Responses

If a JSON response is returned, it will have an ok field that is true if the call succeeded and false if there was an error. An unsuccesful response has the form:

{ "ok": false, "errors": [strings], "error_code": number }

errors are error messages and error_code is one of:

  • 1 = Authentication error (auth_token, auth_sig, or app_id not correct for this operation)
  • 2 = App configuration error (auth_token not approvoved etc)
  • 3 = Invalid request (bad parameters)
  • 4 = Exists (trying to create something that already exists)
  • 5 = Not found (trying to reference an ID that doesn't exist)
  • -1 = Internal error (not your fault; try again)

Result Methods

back to top

get-recommendations

get-recommendations returns the most strongly recommended results for the authenticated user or one of their friends, within a set of possible results restricted by topic, site, result id, or location. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
topic_ids optional List of topic ids. Only results in these topics will be returned as recommendations. topic_ids=list_book,cat_tech
sites optional List of site names. Only results from these sites will be returned as recommendations. sites=hn,fb
result_ids optional List of result ids. Only results in this list will be returned as recommendations. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only results in this bounding circle will be returned as recommendations. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only results in this bounding rectangle will be returned as recommendations. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only results whose names or tags contain this string will be returned as recommendations. query=metropolitan museum
name optional A string. Only results whose names contain this string will be returned as recommendations. name=metropolitan museum
tags optional A string. Only results whose tags contain this string will be returned as recommendations. tags=art museum
urls optional A list of URLs. Only results with URLs in this list will be returned as recommendations. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Results in these topics will not be returned as recommendations. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Results in these sites will not be returned as recommendations. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. These results will not be returned as recommendations. blocked_result_ids=hn_217541,fb_1399372782
exclude_likes optional A boolean, defaulting to false. If true, results that have been liked by the user will not be returned as recommendations. exclude_likes=1
exclude_dislikes optional A boolean, defaulting to true. If true, results that have been disliked by the user will not be returned as recommendations. exclude_dislikes=0
minimal optional A boolean, defaulting to false. If true, only result ids will be returned, without result data such as names and descriptions. minimal=1
exclude_chains optional A boolean, defaulting to false. If true, results that are known chain businesses will not be returned as recommendations. exclude_chains=1
likes optional A list of result ids. The user's tastes will temporarily incorporate their positive preference for these results. likes=hn_217541,fb_1399372782
dislikes optional A list of result ids. The user's tastes will temporarily incorporate their negative preference for these results. dislikes=hn_217541,fb_1399372782
responses optional A list of Teach Hunch About You response ids. The user's tastes will temporarily incorporate these responses. responses=hn_1386554,hn_3006174
limit optional An integer, defaulting to 10. At most this many recommendations will be returned. limit=15
offset optional An integer, defaulting to 0. This many of the top recommendations will be skipped, and only recommendations lower than these will be returned. offset=15
wildcards optional A boolean, defaulting to false. If true, some recommendations will randomly appear higher than they normally would. wildcards=1
app_id auth_sig user_id optional Application credentials, proving that the call originated from your app. user_id must be for your app, in which case it can be passed instead of an auth_token. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70&user_id=myapp_fyodor
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "is_personalized": boolean, "total": number, "recommendations": [recommendations] }

is_personalized will be true if and only if there was taste data available for the user. total is the total number of recommendations before limit and offset are applied.

recommendations are ordered by score, and each has the form:

{ "result_id": id, "stars": number, "is_predicted": boolean, "score": score, "name": string, "url": url, "image_url": url, "aliases": [ids], "topic_ids": [ids], "preferences": [preferences], "tags": [strings], "urls": [urls], "image_urls": [urls], ... }

Note that recommendations also include a deprecated title field for backwards-compatibility, but you should use the name field instead.

is_predicted will be false if and only if the user has actually rated the item, in which case stars will represent their given rating. aliases is a list of all result ids aliased to this result. topic_ids is a list of the topic ids the result and its aliases were found in. Many results also have other fields, including lat, lng, address, phone, and more.

preferences are ordered by date, unless the authenticated user has a preference in which case it comes first. Each has the form:

{ "user_id": id, "types": [strings], "stars": number, "created": date, "user_name": string, "user_url": url, "user_image_url": url }
back to top

get-results

get-results returns a set of results restricted by topic, site, result id, or location. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
topic_ids optional List of topic ids. Only results in these topics will be returned. topic_ids=list_book,cat_tech
sites optional List of site names. Only results from these sites will be returned. sites=hn,fb
result_ids optional List of result ids. Only results in this list will be returned. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only results in this bounding circle will be returned. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only results in this bounding rectangle will be returned. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only results whose names or tags contain this string will be returned. query=metropolitan museum
name optional A string. Only results whose names contain this string will be returned. name=metropolitan museum
tags optional A string. Only results whose tags contain this string will be returned. tags=art museum
urls optional A list of URLs. Only results with URLs in this list will be returned. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Results in these topics will not be returned. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Results in these sites will not be returned. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. These results will not be returned. blocked_result_ids=hn_217541,fb_1399372782
minimal optional A boolean, defaulting to false. If true, only result ids will be returned, without result data such as names and descriptions. minimal=1
limit optional An integer, defaulting to 10. At most this many results will be returned. limit=15
offset optional An integer, defaulting to 0. This many results will be skipped, and only results after these will be returned. offset=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "total": number, "results": [results] }

total is the total number of results before limit and offset are applied.

Each result has the form:

{ "result_id": id, "name": string, "url": url, "image_url": url, "aliases": [ids], "topic_ids": [ids], "preferences": [preferences], "tags": [strings], "urls": [urls], "image_urls": [urls], ... }

Note that results also include a deprecated title field for backwards-compatibility, but you should use the name field instead.

aliases is a list of all result ids aliased to this result. topic_ids is a list of the topic ids the result and its aliases were found in. Many results also have other fields, including lat, lng, address, phone, and more.

preferences are ordered by date, unless the authenticated user has a preference in which case it comes first. Each has the form:

{ "user_id": id, "types": [strings], "stars": number, "created": date, "user_name": string, "user_url": url, "user_image_url": url }
back to top

get-similar-results

get-similar-results returns the most similar results to a given result, within a set of results restricted by topic, site, result id, or location. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
result_id required A result id. Results will be ranked by their similarity to this result. result_id=hn_217541
topic_ids optional List of topic ids. Only results in these topics will be returned. topic_ids=list_book,cat_tech
sites optional List of site names. Only results from these sites will be returned. sites=hn,fb
result_ids optional List of result ids. Only results in this list will be returned. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only results in this bounding circle will be returned. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only results in this bounding rectangle will be returned. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only results whose names or tags contain this string will be returned. query=metropolitan museum
name optional A string. Only results whose names contain this string will be returned. name=metropolitan museum
tags optional A string. Only results whose tags contain this string will be returned. tags=art museum
urls optional A list of URLs. Only results with URLs in this list will be returned. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Results in these topics will not be returned. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Results in these sites will not be returned. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. These results will not be returned. blocked_result_ids=hn_217541,fb_1399372782
limit optional An integer, defaulting to 10. At most this many results will be returned. limit=15
offset optional An integer, defaulting to 0. This many results will be skipped, and only results after these will be returned. offset=15
wildcards optional A boolean, defaulting to false. If true, some results will randomly appear higher than they normally would. wildcards=1
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "results": [results] }

results are ordered by score, and each has the form:

{ "score": number, "result_id": id, "name": string, "url": url, "image_url": url }
back to top

flag-result

flag-result flags a result for review, in the context of a given topic. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result to flag. result_id=hn_217541
topic_id required Topic id, identifying the topic in which the result should be flagged. topic_id=list_book
message optional String describing the reason for the flag. message=Closed restaurant.
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }

User Methods

back to top

get-auth-token

get-auth-token returns an authentication token for the authentication token key received after the user is redirected from http://hunch.com/authorize/. Alternatively, trusted apps can authenticate using another auth_token or basic_auth. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
app_id auth_sig required Application credentials, proving that the call originated from your app. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70
auth_token_key optional An authorization token key, received in the redirect url from http://hunch.com/authorize/. auth_token_key=7a1b2c3
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "user_id": id, "auth_token": token }
back to top

get-token-status

get-token-status returns the status of the given authentication token, indicating whether the token has been accepted or rejected by the user. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
app_id auth_sig required Application credentials, proving that the call originated from your app. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70
token required An authorization token, received from get-auth-token. token=4d3d3d3
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "status": string }

status is either 'pending', 'accepted', or 'rejected'.

back to top

get-user

get-user returns information about the authenticated user, or another specified Hunch user. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
user_id optional A Hunch user id. If provided, this user's information will be returned. Otherwise, the authenticated user's information will be returned. user_id=hn_5899344
limit optional An integer, defaulting to 0. At most this many of the user's feed recommendations will be returned. limit=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "username": string, "url": string, "image_url": string, "rating_count": number, "save_count": number, "followee_count": number, "follower_count": number, "feed_recommendation_count": number, "feed_recommendations": [results], "name": string, "first_name": string,  "about": string, "website": string, "address": string, "lat": number, "lng": number, "tags": [strings]}
back to top

get-friends

get-friends returns the friends of the authenticated user. This includes their mutual Hunch followers, mutual Twitter followers if they are Twitter-connected, and Facebook friends if they are Facebook-connected. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
sites optional List of site names. Only friends from these sites will be returned. sites=hn,fb
friend_ids optional List of user ids. Only friends in this list will be returned. friend_ids=hn_1523244,fb_700470
sort optional A string, identifying a key to sort friends by. Friends will be returned in order of this key, or randomly if 'random' is passed. sort=days_until_birthday
reverse optional A boolean, defaulting to false. Reverses the order in which friends are returned. reverse=1
limit optional An integer, defaulting to 10. At most this many friends will be returned. limit=15
offset optional An integer, defaulting to 0. This many friends will be skipped, and only friends after that will be returned. offset=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "total": number, "friends": [friends] }

total is the total number of friends before limit and offset are applied.

Each friend has the form:

{ "user_id": id, ... }

Most friends will have several additional fields, including name, first_name, last_name, birthday, gender, and more.

back to top

get-tastemates

get-tastemates returns the most similar friends of the authenticated user, in terms of their affinity to a set of results restricted by topic, site, result id, or location. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
topic_ids optional List of topic ids. Only results in these topics will affect similarities. topic_ids=list_book,cat_tech
sites optional List of site names. Only results from these sites will affect similarities. sites=hn,fb
result_ids optional List of result ids. Only results in this list will affect similarities. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only results in this bounding circle will affect similarities. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only results in this bounding rectangle will affect similarities. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only results whose names or tags contain this string will affect similarities. query=metropolitan museum
name optional A string. Only results whose names contain this string will affect similarities. name=metropolitan museum
tags optional A string. Only results whose tags contain this string will affect similarities. tags=art museum
urls optional A list of URLs. Only results with URLs in this list will affect similarities. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Results in these topics will not affect similarities. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Results in these sites will not affect similarities. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. These results will not affect similarities. blocked_result_ids=hn_217541,fb_1399372782
limit optional An integer, defaulting to 10. At most this many tastemates will be returned. limit=15
offset optional An integer, defaulting to 0. This many tastemates will be skipped, and only tastemates after these will be returned. offset=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "tastemates": [tastemates] }

tastemates are ordered by score, and each has the form:

{ "user_id": id, "score": number, ... }

Most tastemates will have several additional fields, including name, first_name, last_name, birthday, gender, and more.

back to top

get-recommendees

get-recommendees returns the authenticated user's friends for whom the given item is most strongly recommended. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required A result id. Users will be ranked by their affinity for this result. result_id=hn_217541
limit optional An integer, defaulting to 10. At most this many users will be returned. limit=15
offset optional An integer, defaulting to 0. This many users will be skipped, and only users after these will be returned. offset=15
wildcards optional A boolean, defaulting to false. If true, some users will randomly appear higher than they normally would. wildcards=1
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "recommendees": [recommendees] }

recommendees are ordered by score, and each has the form:

{ "user_id": id, "score": number, ... }

Most recommendees will have several additional fields, including name, first_name, last_name, birthday, gender, and more.

Topic Methods

back to top

get-result-topics

get-result-topics searches within the same set of possible results as get-results, returning all topics containing those results. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
topic_ids optional List of topic ids. Only results in these topics will be searched. topic_ids=list_book,cat_tech
sites optional List of site names. Only results from these sites will be searched. sites=hn,fb
result_ids optional List of result ids. Only results in this list will be searched. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only results in this bounding circle will be searched. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only results in this bounding rectangle will be searched. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only results whose names or tags contain this string will be searched. query=metropolitan museum
name optional A string. Only results whose names contain this string will be searched. name=metropolitan museum
tags optional A string. Only results whose tags contain this string will be searched. tags=art museum
urls optional A list of URLs. Only results with URLs in this list will be searched. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Results in these topics will not be searched. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Results in these sites will not be searched. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. These results will not be searched. blocked_result_ids=hn_217541,fb_1399372782
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "topics": [topics] }

Each topic has the form:

{ "topic_id": id, "name": string, ... }

Topics may also have other fields, such as tags, url, and more.

back to top

get-topics

get-topics returns information about topics and their subtopics. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
topic_ids optional List of topic ids. Data will be returned for these topics and their subtopics. topic_ids=list_book,cat_tech
sites optional List of site names. Only topics from these sites will be returned. sites=hn,fb
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "topics": [topics] }

Each topic has the form:

{ "topic_id": id, "name": string, "subtopics": [topics], ... }

Topics may also have other fields, such as tags, url, and more.

Preference Methods

back to top

get-activity

get-activity returns recent Hunch API activity, optionally restricted to a particular set of results. This activity includes preferences of the authenticated user, likes of their friends, and favorites of all API users. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
user_ids optional List of user ids. Only activity of users in this list will be returned. user_ids=hn_1523244,fb_700470
topic_ids optional List of topic ids. Only activity for results in these topics will be returned. topic_ids=list_book,cat_tech
sites optional List of site names. Only activity for results from these sites will be returned. sites=hn,fb
result_ids optional List of result ids. Only activity for results in this list will be returned. result_ids=hn_217541,fb_1399372782
lat lng radius optional Bounding circle, specified in degrees and miles. Only activity for results in this bounding circle will be returned. lat=40.74&lng=-74.00&radius=1.5
minlat maxlat minlng maxlng optional Bounding rectangle, specified in degrees. Only activity for results in this bounding rectangle will be returned. minlat=40.74&maxlat=40.75&minlng=-74.01&maxlng=-73.97
query optional A string. Only activity for results whose names or tags contain this string will be returned. query=metropolitan museum
name optional A string. Only activity for results whose names contain this string will be returned. name=metropolitan museum
tags optional A string. Only activity for results whose tags contain this string will be returned. tags=art museum
urls optional A list of URLs. Only activity for results with URLs in this list will be returned. urls=http://www.kayak.com/,http://hunch.com/item/hn_1
blocked_topic_ids optional List of topic ids. Activity for results in these topics will not be returned. blocked_topic_ids=list_book,cat_tech
blocked_sites optional List of site names. Activity for results in these sites will not be returned. blocked_sites=hn,fb
blocked_result_ids optional List of result ids. Activity for these results will not be returned. blocked_result_ids=hn_217541,fb_1399372782
limit optional An integer, defaulting to 10. At most this many preferences will be returned. limit=15
offset optional An integer, defaulting to 0. This many preferences will be skipped. offset=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "activity": [preferences] }

activity is ordered by date.

Each preference has the form:

{ "user_id": id, "types": [strings], "preference": number, "confidence": number, "created": date, "user_name": string, "user_url": url, "user_image_url": url }
back to top

get-preferences

get-preferences returns the preferences of the authenticated user. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_ids optional List of result ids. Only preferences for these results will be returned. result_ids=hn_217541,fb_1399372782
sites optional List of site names. Only preferences for results from these sites will be returned. sites=hn,fb
types optional A list of preference types from 'like', 'dislike', 'favorite', 'checkin', 'purchase', 'return', 'click', 'share', 'rate', 'guess-like', 'guess-dislike', '*hate', '*dislike', '*okay', '*like', '*love', or 'not-interested'. Only preferences set with these types will be returned. types=purchase,*love
user_id optional A user id. This user's preferences will be returned instead of the authenticated user's. user_id=hn_5899344
before optional A datetime in ISO format. Only preferences expressed before this time will be returned. before=2011-02-11 02:11:00
after optional A datetime in ISO format. Only preferences expressed after this time will be returned. after=2011-02-11 02:11:00
limit optional An integer, defaulting to 10. At most this many predictions will be returned. limit=15
offset optional An integer, defaulting to 0. This many of the top predictions will be skipped, and only predictions lower than these will be returned. offset=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "preferences": [preferences] }

preferences are ordered by date, and each has the form:

{ "result_id": id, "types": [strings], "preference": number, "confidence": number, "created": date, "result_name": string, "result_url": url, "result_image_url": url }
back to top

set-preference

set-preference records a preference for the authenticated user, or a guess preference for a friend of the authenticated user. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result the preference applies to. result_id=hn_217541
types required A list of preference types. Each type must be one of 'favorite', 'like', 'dislike', 'checkin', 'purchase', 'return', 'click', 'share', 'rate', '*hate', '*dislike', '*okay', '*like', '*love', or 'not-interested'. Types beginning with '*' correspond to star ratings on hunch.com. If friend_id is passed, each type must be one of 'guess-like' or 'guess-dislike'. types=purchase,*love
rating optional A number between 0 and 1, representing the user's rating of the item, where 0 denotes dislike and 1 denotes like. Use if and only if the 'rate' type is given. rating=0.8
friend_id optional A user id, which must refer to a friend of the authenticated user. A guess preference type must be passed, and will be recorded for this user. friend_id=fb_700470
app_id auth_sig user_id optional Application credentials, proving that the call originated from your app. user_id must be for your app, in which case it can be passed instead of an auth_token. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70&user_id=myapp_fyodor
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }
back to top

delete-preference

delete-preference removes a preference for the authenticated user, or a guess preference for a friend of the authenticated user. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result whose preferences should be deleted. result_id=hn_217541
topic_ids optional List of topic ids. If specified, only preferences in these topics will be deleted. topic_ids=list_book,cat_tech
types optional A list of preference types. If specified, only preferences of these types will be deleted. Each type must be one of 'favorite', 'like', 'dislike', 'checkin', 'purchase', 'return', 'click', 'share', 'rate', '*hate', '*dislike', '*okay', '*like', '*love', or 'not-interested'. Types beginning with '*' correspond to star ratings on hunch.com. If friend_id is passed, each type must be one of 'guess-like' or 'guess-dislike'. types=purchase,*love
friend_id optional A user id, which must refer to a friend of the authenticated user. Guess preference types must be passed. friend_id=fb_700470
app_id auth_sig user_id optional Application credentials, proving that the call originated from your app. user_id must be for your app, in which case it can be passed instead of an auth_token. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70&user_id=myapp_fyodor
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }

THAY Methods

back to top

get-predictions

get-predictions returns the most strongly predicted Teach Hunch About You responses for the authenticated user, potentially restricted to a set of possible responses. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
allowed_qids optional List of question ids. Only responses to these questions will be returned as predictions. allowed_qids=hn_4172,hn_849344
blocked_qids optional List of question ids. Responses to these questions will not be returned as predictions. blocked_qids=hn_4172,hn_849344
blocked_rids optional List of response ids. These responses will not be returned as predictions. blocked_rids=hn_1386554,hn_3006174
avoid_rids optional List of response ids. Responses which are highly-correlated to any of these responses will not be returned as predictions. avoid_rids=hn_1386554,hn_3006174
likes optional A list of result ids. The user's tastes will temporarily incorporate their positive preference for these results. likes=hn_217541,fb_1399372782
dislikes optional A list of result ids. The user's tastes will temporarily incorporate their negative preference for these results. dislikes=hn_217541,fb_1399372782
responses optional A list of Teach Hunch About You response ids. The user's tastes will temporarily incorporate these responses. responses=hn_1386554,hn_3006174
limit optional An integer, defaulting to 10. At most this many predictions will be returned. limit=15
offset optional An integer, defaulting to 0. This many of the top predictions will be skipped, and only predictions lower than these will be returned. offset=15
app_id auth_sig user_id optional Application credentials, proving that the call originated from your app. user_id must be for your app, in which case it can be passed instead of an auth_token. app_id=12345&auth_sig=941bc415af782a8d93a83c874922ae1b30e92a70&user_id=myapp_fyodor
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "is_personalized": boolean, "total": number, "predictions": [predictions] }

is_personalized will be true if and only if there was taste data available for the user. total is the total number of predictions before limit and offset are applied.

predictions are ordered by score, and each has the form:

{ "question_id": id, "response_id": id, "score": number, "question_text": string, "question_image_url": url, "response_text": string, "response_image_url": url, "response_popularity": number, "responses": [responses] }

responses contains all possible responses to the question, each of which has the form:

{ "response_id": id, "response_text": string, "response_image_url": url, "response_popularity": number }
back to top

get-questions

get-questions returns data for given Teach Hunch About You questions, or returns the next questions to be asked to the authenticated user. Also, if the authenticated user has responded to any of the returned questions, their responses will be returned. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token optional An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
question_ids optional A list of question ids, identifying the questions to be returned. question_ids=hn_212,hn_917054
limit optional An integer, defaulting to the numer of question_ids, or 10 if no question_ids are provided. At most this many questions will be returned. limit=15
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, questions: [questions] }

Each question has the form:

{ "question_id": id, "question_text": string, "question_image_url": url, "responses": [responses], ... }

If the authenticated user has responded to the question, their chosen response will also be included in the question object, as response_id.

responses contains all responses to the question, each of which has the form:

{ "response_id": id, "response_text": string, "response_image_url": url }
back to top

teach-hunch-about-you

teach-hunch-about-you records the authenticated user's response to a Teach Hunch About You question. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
question_id required A question id, identifying the question the user answered. question_id=hn_212
response_id optional A response id, identifying the response the user chose. If not provided, then the user is recorded as having 'skipped' the given question. response_id=hn_111
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, questions: [questions] }

Each question has the form:

{ "question_id": id, "question_text": string, "question_image_url": url, "responses": [responses] }

responses contains all responses to the question, each of which has the form:

{ "response_id": id, "response_text": string, "response_image_url": url }

Feed Methods

back to top

save-result

save-result saves a result in the authenticated user's Hunch Feed. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result to be saved. result_id=hn_217541
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }
back to top

recommend-result

recommend-result recommends a result in the authenticated user's Hunch Feed. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result to be recommended. result_id=hn_217541
recommendation required A string, providing the text of the user's recommendation. recommendation=My favorite neighborhood restaurant!
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }
back to top

delete-save

delete-save removes the authenticated user's save of a result they've previously saved in the Hunch Feed. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result whose save should be deleted. result_id=hn_217541
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }
back to top

delete-recommendation

delete-recommendation removes the authenticated user's recommendation from a result they've previously recommended in the Hunch Feed. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
auth_token required An authorization token, authenticating your app on behalf of the user. auth_token=0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5
result_id required Result id, identifying the result whose recommendation should be deleted. result_id=hn_217541
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true }

Special Methods

back to top

batch

batch combines multiple API calls into one. This can be useful for reducing latency, especially in mobile applications. Calls are executed in the order they are given; if a call fails then no calls after it are executed. (view in console)

Input Parameters (show)

NameRequiredDescriptionExample
calls required A JSON array, listing the desired method calls. calls=
[
 {"name": "get-results",
  "params":
   {"topic_ids": "list_book,cat_tech",
    "query": "metropolitan museum",
    "limit": 10}},
 {"name": "get-preferences",
  "params":
   {"auth_token": "0ff2a464e782fd46c3648b23d0b7eabaa9b5afd5"}}
]
callback optional A JSONP callback. This will be prepended to the parenthesized response, which will be returned as text/javascript. callback=myFunc
suppress_http_errors optional A boolean, defaulting to false. If true, even error responses will have an HTTP response code of 200. suppress_http_errors=1

Response Structure (show)

A successful response has the form:

{ "ok": true, "responses": [responses] }

responses are the responses, in the same order, to each call in the calls parameter.

An unsuccesful response has the form:

{ "ok": false, "errors": [strings], "error_code": number, "responses": [responses] }

responses are the responses, in the same order, to each call in the calls parameter, up to and including the call which failed. All responses after the failed call are null.