Otus Labs - Profiling API Documentation

2 | 5 © Jan 2015

JSON Format We both accept and respond with JSON for all calls made to the Otus Profiling API. Where we process social data, such as Facebook likes, we have made every effort to keep the exact same formatting. Required Parameters Every request needs a valid API key and you can set this value as an HTTP parameter. API Restrictions Depending on your use case and your agreement with us, certain endpoints and parameters may not be available to your API key. That said all clients will gain access to the core functionality of the Add, Update and Summarise User endpoints. Beta Functionality We are constantly trying to improve our API and release new functionality that can help you gain an even clearer understanding of who your users are and what your audience as a whole looks like. Beta functionality is only available to those companies who request it and is always provided outside of any service level agreement. For reference we have included some Beta functionality below which is close to full public release, but we have made sure this is clearly marked as such. Terms of Use & Request Rate Limiting The use of the Otus Profiling API is governed by our Terms of Use which include a dedicated rate limit set on a case by case basis for each client. You will need to have read, agreed and signed our Terms of Use before an API key will be issued. More Information For more information on how the Otus Profiling API works or how it could help you, please contact us through our website or via api@otuslabs.com.

Otus Labs - Profiling API Documentation

3 | 5 © Jan 2015

Reference: Add User POST http://api.otuslabs.com/add_user?api_key=<your_key> POST body: { "user_id": "0000000001", "gender": "M", "birthday": "30/12/2014", "user_groups": [ "group1", "group2", "group3"] , "fb_likes": [ { "category": "Internet/software", "category_list": [ { "id": "358483060859947", "name": "Startup" } ], "name": "Otus Labs", "created_time": "2014-09-06T11:03:46+0000", "id": "247140068746764" } ] } Update User POST http://api.otuslabs.com/update_user?api_key=<your_key> POST body: { "user_id": "0000000001", "user_groups": [ "group4", "group5"] , "fb_likes": [ { "category": "Movie", "name": "Nightcrawler UK", "created_time": "2014-10-26T22:20:17+0000", "id": "1499463963603649" } ] }

Description The Add User endpoint is used to add a new user to our system, with associated entities and additional information. This endpoint is built to return quickly providing a brief initial overview of your user’s interests and relevancy scores. It’s important to note that each user can only be added once.

Description The Update User endpoint is used to update information relating to a user who had previously been added to our system. It’s important to note that this endpoint will only append information to a user and won’t overwrite data.

Otus Labs - Profiling API Documentation

4 | 5 © Jan 2015

Add & Update User Parameters Field Name Description Type Status

"user_id" Unique user ID – For privacy reasons we suggest you don’t use the users public Facebook ID. String Required

"gender" This is the user’s gender – We accept either “M” of “F” String Optional

"birthday" This is the user’s date of birth – We accept this is a MM/DD/YYYY format. Date Optional

"user_groups" This allows you to group users into cohorts – This is important when it comes providing accurate affinity scores, benchmarking info and so you can compare two users to each other.

Array [string] Private Beta

"fb_likes" This is the same JSON array [object] that is returned by Facebook containing all the users “Like” information. – This will allow us to analyse all the Facebook pages a user has liked.

Array [object] Optional

"fb_feed" This is the same JSON array [object] that is returned by Facebook containing all the users “feed” information. – This will allow us to analyse content that the user has shared.

Array [object] Private Beta

"twitter" This is a JSON array [object] that allows you to pass us the accounts a user follows alongside their latest tweets. Array [object] Private Beta

Summarise User The Summarise User endpoint is used to generate an up to date full profile of an existing user. This profile is generated on request and will change over time as our knowledge of entities and articles is constantly evolving. GET http://api.otuslabs.com/summarise_user?api_key=<your_key>?user_id=0000000001 API Responses Response Relates to Status

Sorry, the API key is not valid All Error

Sorry, you are not authorized to use this endpoint All Error

Unable to process your request, sorry about that :(. Contact us if issues persist. All Error

User already exists Add User Error

User does not exist Update User Error

Update submitted Update User Success

JSON Profile - See next page Add User & Summarise User Success

Otus Labs - Profiling API Documentation

5 | 5 © Jan 2015

Add & Summarise User Response { "labels": [ { "id": 30, "label": ".entity.film_and_television.action_and_adventure.espionage", "score": 9.234, }, { "id": 1817, "label": ".entity.industry.mass_media.journalism", "score": 7.659, }, { "id": 1977, "label": ".entity.literature.non-fiction.technology_books", "score": 4.834, } { "id": 2006, "label": ".entity.food_and_drink.non-alcoholic_drinks.tea", "score": 8.834, } ] } Interest Label Ontology All interest labels returned in the above response are structured in a hierarchical label ontology, which its structure can be observed through the dotted notations provided. We currently return interest labels in seven distinct verticals; Film & TV, Food & Drink, Industry, Issues & Charitable Causes, Literature, Music and Sport. Get Ontology GET http://api.otuslabs.com/get_ontology?api_key=<your_key> Example Response { "id": 1, "label": ".entity ", "niceName": "Entity ", "children": [ { "id": 2, "label": ".entity.film_and_television", "niceName": "Film & TV ", "children": [ { "id": 2177, "label": ".entity.film_and_television.live_tv", "niceName": "Live TV ", "children": [

Description This is a sample of the JSON response you receive on adding a new user or summarising an existing one. As you can see our current response only contains interest “labels”, but in the near future this will contain further profiling info. Label scores are provided to give you an understanding of how interested a user is in each vertical and specific topic, with a higher score indicating higher relevancy.

Description Our Get Ontology endpoint can provide you with a full copy of our latest label ontology, including a formatted "nice name" for each individual label. We currently provide labels for nearly 2000 interests across seven key verticals.