05 API Interactions I.

1. Anne Schuth (Blendle / University of Amsterdam, The Netherlands) Krisztian Balog (University of Stavanger, Norway) Tutorial at ECIR 2016 in Padua, Italy API Interactions I.
2. Overview Participant Participant Site Site Living Labs API Researcher query ranking query ranking ranking Queries Documents click click click Queries Documents API for participants
3. Outline for API interactions • Obtaining an API key and signing up for a site • Getting queries and candidate items • Generating and uploading rankings • Obtaining feedback and outcome
4. Keep in mind • The CLEF and TREC APIs have different URLs • We will use the CLEF API during the practical sessions
5. Obtaining an API key • Go to http://dashboard.living-labs.net/ • Click Register
6. Account verification • We will activate you for the day and deactivate unless you send us the signed form
7. Sign up for site • Sign up for the REGIO Jatek site
8. Get ready to code! • Go to http://living-labs.net/tutorial/ and click on the DataJoy (exercises) link to get the starter files • Make a new DataJoy project in a new browser window, copy-paste the starter files, and try to complete the code individually • Fill in your API key! • You can follow the presenter’s screen on the link above
9. DataJoy • Click Menu / Install packages • Search for "whoosh" • Install
10. Outline for API interactions • Obtaining an API key and signing up for a site • Getting queries and candidate items • Generating and uploading rankings • Obtaining feedback and outcome
11. Getting queries Living Labs API Researcher ranking click Queries Documents
12. Query endpoint • GET /api/participant/query/(key) • Returns the query set for all sites that you have subscribed for • Each query has a unique qid • A query can be train or test
13. Example { "queries": [ { "creation_time": "Wed, 22 Apr 2015 09:15:41 -0000", "qid": "R-q1", "qstr": "monster high", "type": "train" }, { "creation_time": "Wed, 22 Apr 2015 09:15:41 -0000", "qid": "R-q51", "qstr": "puzzle", "type": "test" } ] } GET http://api.living-labs.net/api/
 participant/query/(key)
14. Getting candidate items (documents) • For each query, there is a fixed set of items (documents) available • Candidate items are selected by the site and may change over time • Participants cannot return items outside this candidate set for the query • Quality control to avoid nonsense results
15. Doclist endpoint • GET /api/participant/doclist/(key)/ (qid) • Returns the set of documents that are allowed results for a given query • Each document has a unique docid
16. Example { "doclist": [ { "docid": "R-d1291", "site_id": "R", "title": "LEGO DUPLO Hamupip\u0151ke hint\u00f3ja 6153" }, { "docid": "R-d1306", "site_id": "R", "title": "LEGO Rend\u0151rkapit\u00e1nys\u00e1g 5681" }, { "docid": "R-d1308", "site_id": "R", "title": "LEGO City Rugalmas s\u00ednek 7499" }, GET http://api.living-labs.net/api/
 participant/doclist/(key)/R-q3
17. Getting items (documents) Living Labs API Researcher ranking click Queries Documents
18. Doc endpoint • GET /api/participant/doc/(key)/(docid) • Returns the contents of a given document
19. Example { "content": { "age_max": 3, "age_min": 1, "arrived": "2014-08-28", "available": 0, "brand": "Lego", "category": "LEGO", "category_id": "38", "characters": [], "description": "Lego Duplo - \u00c9p\u00edt\u0151-\u00e9s j\u00e1t \u00e9kkock\u00e1k kicsiknek 10553<br />[…]", "gender": 0, "main_category": "\u00c9p\u00edt\u0151j\u00e1t\u00e9k, LEGO", "main_category_id": "5", "photos": [ "http://regiojatek.hu/data/regio_images/normal/20526_0.jpg", "http://regiojatek.hu/data/regio_images/normal/20526_1.jpg", GET http://api.living-labs.net/api/
 participant/doc/(key)/R-d84
21. Exercise • Code for creating a single index of all candidate products for the first 5 training queries is given in 01_indexing.py • Extend the index to • Include more fields • Create a "catch-all" text field