- Previous:
- Up:
- Next: How to Interpret a Vector Set
Whit.li Documentation
The Whit.li API is a RESTful web service designed to be easy to explore and use. It is our hope that through the base URI, a developer getting started with our API will be able to reach and manipulate our APIs without reading through multiple pages of documentation. This is accomplished by linking related resources and providing instructions on how to use each representation (link templates) in the response itself.
For a dynamic view of our documentation, try our IO Docs! IO Docs allows you to make live calls to our APIs while getting a stronger understanding for all of the resources and parameters involved.
Getting Started with the API
Let's take a quick exploratory dive into the API and see this thing in action. To start out on our journey, simply register for a Whit.li API key. We currently support responses in JSON, with future plans to support other data formats.
!
User / ImportToken
Description: Import a facebook uid and oauth_token combination to allow Whit.li to populate profile, post and interest information. The call imports the token and populates the data from Facebook. The optional bypass parameter is used to bypass the automatic population from Facebook so that Tokens can be batch processed using the User/Populate Call. If using bypass, set bypass=true in the request body.
Method: POST
Request URI
https://api.whit.li/user/importToken?api_key=
Sample Call
api.whit.li/user/importToken?api_key=mv3nv2uepwfrshvzp4xhxtz
Sample Request Body
Without bypass parameter (populate is done with import)
uid=5544332211&oauth_token=AAACEdEose0cBAE2L0Ce5smFxCEui40XTgeXuXnZCmU1eYqyNjEBM1bx5WSnf0Ew38bkBQZARGzeZAv5Tg4RQTkI9W4R61C258gmZBWwbbAZDZD&format=json
With bypass parameter (populate is not done with import)uid=5544332211&oauth_token=AAACEdEose0cBAE2L0Ce5smFxCEui40XTgeXuXnZCmU1eYqyNjEBM1bx5WSnf0Ew38bkBQZARGzeZAv5Tg4RQTkI9W4R61C258gmZBWwbbAZDZD&format=json&bypass=true
Sample Response Header
{
"Content-Type":"application/json",
"Date":"Fri, 17 Feb 2012 20:59:05 GMT",
"Server":"Apache",
"X-Mashery-Responder":"prod-javaproxy-worker-us-west-1c-10.mashery.com",
"X-Trace":"1B3A2F7B2772F1B981CXA4A3XA637C81752ADX5E72BAAD37193853CCB8",
"Content-Length":"72",
"Connection":"keep-alive"
}
Sample Response Body
Without bypass=true parameter
{
"status":"success",
"message":"facebook data retreived successfully",
"body":{
"userFields":40,
"likesCount":179,
"postsCount":18
},
"timestamp":1329512970
}With bypass = true parameter
{"status":"success","message":
"user token stored successfully","timestamp": 1342195103}
!
User / Populate
Description: Request Whit.li to refresh data associated with a given uid and oauth_token pair.
Method: GET
Request URI
https://api.whit.li/user/populate?uid=&format=json&api_key=
Sample Call
https://api.Whit.li/user/populate?uid=5544332211&format=json&api_key=qhs9n37bq5uxxf5cr4wucxrw
Sample Response Header
{
"Content-Type":"application/json",
"Date":"Fri, 17 Feb 2012 21:09:24 GMT",
"Server":"Apache",
"X-Mashery-Responder":"prod-javaproxy-worker-us-west-1b-09.mashery.com",
"Content-Length":"150",
"Connection":"keep-alive"
}
Sample Response Body
{
"status":"success",
"message":"facebook data retreived successfully",
"body":{
"userFields":40,
"likesCount":179,
"postsCount":18
},
"timestamp":1329512970
}
!
User / ImportGeneric
Description: If you have user generated content and profiles, for example from a forum, reviews or a community site, you can use that information as inputs into Whit.li’s algorithms instead of pulling data from Facebook.
Method: PUT
Request URI:
https://api.whit.li/user/importGeneric?api_key=
Sample Call
https://api.whit.li/user/importGeneric?api_key=yzr7cmxbxr5xvrxxrw324ey
Sample Request Body
{
"schema":"generic",
"uid":"1",
"profile_data":{
"first_name":"John",
"last_name":"Whitli",
"hometown_location":"Austin, Tx",
"work_history":[
{
"location":{
"city":"Austin",
"state":"Texas"
},
"company_name":"Whit.li- Explore Minds Like Yours",
"position":"Emperor",
"description":"",
"start_date":"2011-04"
}
]
},
"posts":[
{
"id":"152543539_10150215025383600",
"message":"this is a post",
"created_time":"2011-12-09T15:46:23+0000"
},
{
"id":"152543539_10150107473533600",
"message":"this is a post",
"created_time":"2011-12-08T15:46:23+0000"
}
],
"likes":[
{
"name":"The Black Keys",
"id":"8746730308",
"category":"Musician\/band",
"created_time":"2010-05-07T16:35:29+0000"
},
{
"name":"Austin, Texas",
"id":"4034730278",
"category":"Community",
"created_time":"2010-05-06T16:35:29+0000"
},
{
"name":"Michio Kaku",
"id":"111722405511675",
"category":"Author",
"created_time":"2010-05-07T16:35:29+0000"
}
]
}
Sample Response Body
{
"status":"success",
"mesasge":"data submitted successfully",
"body":{
"userFields":4,
"likesCount":3,
"PostsCount":3
},
"timestamp":1329254595
}
!
Key / Get
Description: Get a Whit.li key. A Whit.li key contains information that describes the various traits of a person. Each Whit.li key contains multiple vectors that have detailed information about an individual based on the individuals psycho-social profile. There are multiple keys that return different information. Look at Interpreting a vector set to see which key is best for your needs. If you populated data from Facebook set the schema to fb, however, if you imported data with User Import Generic set the schema to generic. Format specifies the output format, options are json, xml, csv, or php.
Method: GET
Request URI
https://api.whit.li/key/get? uid=&key_id=&schema=&format=&api_key=
Sample Call
https://api.whit.li/key/get?uid=55443322111&key_id=1&schema=fb&format=json&api_key=qhs9n37bq5us2f5xrxwucxrw
Sample Response Header
{
"Content-Type":"application/json",
"Date":"Fri, 17 Feb 2012 21:16:28 GMT",
"Server":"Apache",
"X-Mashery-Responder":"prod-javaproxy-worker-us-west-1b-09.mashery.com",
"Content-Length":"190",
"Connection":"keep-alive"
}
Sample Response Body
{
"status":"success",
"message":"params accepted",
"body":{
"key":"K1:V1(1,30.26715,-97.74306,790390,31);V2(1.55,14.6,1.24,2.17,2.8);V3(6.1,0);V4(46,5,8,4,7,13,15,43,9)"
},
"timestamp":1329513388
}
!
Key / Compare
Description: Compare two users based on a given context associated with key vectors and components. For more information on what each context contains check Interpreting a vector set. The call takes two uids (uid1 and uid2), a context_id (100-104, 106), schema (fb or generic, depending on data source), output format (format = json, xml, csv, or php) and the api_key. Also optionally the call can return "rare interests" through the likes parameter. The likes is set to 1 if to return rare interestes and not included to not return rare interests.
NOTE: Before this api call will return meaningful data, a GET Key with key_id = 2 must have been run on both users.
Method: GET
Request URI
https://api.whit.li/key/compare? uid1=&uid2=context_id=&schema=&format=&api_key=&likes=
Sample Call
https://api.whit.li/key/compare?uid1=5544332211&uid2=5544332212&context_id=100&schema=fb&format=json&api_key=qhs9n37bq5xxrx5cr4wucxrw&likes=1
Sample Response Header
{
"Content-Type":"application/json",
"Date":"Fri, 17 Feb 2012 21:16:28 GMT",
"Server":"Apache",
"X-Mashery-Responder":"prod-javaproxy-worker-us-west-1b-09.mashery.com",
"Content-Length":"190",
"Connection":"keep-alive"
}
Sample Response Body
{
"status":"success",
"message":"params accepted",
"body":{
"score":20,
"code":"","common_likes":[{"id":"172109382825604","name":"Whit.li- Explore Minds Like Yours","type":"LOCAL BUSINESS","commonality":"0.3687"
},
"timestamp":1329468124
}
- Previous:
- Up:
- Next: How to Interpret a Vector Set
