Table of Contents. 1 Introduction Connecting to the API HTTP request syntax API release versions... 4

Transcription

1 API Guide

2 Table f Cntents 1 Intrductin Cnnecting t the API HTTP request syntax API release versins Direct Answer API Required parameters Optinal parameters Perfrmance Direct Answer API hell wrld HTTP request XML respnse The XML explained Query API Required parameters Optinal parameters Query API hell wrld HTTP request XML respnse The XML explained Crediting True Knwledge... 12

3 1 Intrductin The True Knwledge API enables develpers t utilize True Knwledge s functinality in third party applicatins. True Knwledge prvides the fllwing API services: the Direct Answer API and the Query API. The Direct Answer API expses the natural language questin answering feature f True Knwledge while the Query API allws users t bypass ur natural language translatin system and directly query the knwledge base using a simple query language. API services are cmprised f HTTP requests and XML respnses. 3

4 2 Cnnecting t the API This chapter details the syntax f the HTTP requests that are used t cmmunicate with the True Knwledge API. 2.1 HTTP request syntax The True Knwledge API is queried using HTTP GET requests. The syntax f these requests is: <hst> The IP address (r name) f the machine that hsts the service. <service name> This is the name f the service. Fr example direct_answer r query. <parameters> One r mre f the HTTP request parameters. Nte that individual parameters must be URL-encded and separated with ampersands. Fr example: nd+actrs&api_accunt_id=[api_username]&api_passwrd=[passwrd] 2.2 API release versins In the future we may release new versins f ur API; we will always strive t make new versins backwards cmpatible with previus releases but in rder t prvide the ptin t ur API users there is the fllwing methd f specifying which API versin yu want t use. If yu wuld like t use the mst recent stable versin then this is the syntax t use: If n versin is specified then stable is the default ptin, s the abve URL is the same as: If yu want t use the latest (but nt necessarily stable) versin f the API this is the syntax t use: If yu want t use a specific versin f the API this is the syntax t use: > 4

5 3 Direct Answer API The Direct Answer API enables develpers t utilize True Knwledge s natural language questin answering technlgy in their wn applicatins. 3.1 Required parameters api_accunt_id=[api_username] passwrd=[passwrd] questin=[url encded questin string] This is where yu specify yur questin. Which shuld be URL encded, e.g. What%27s+the+time+in+Chicag%3F is what yu wuld set fr the questin What s the time in Chicag? 3.2 Optinal parameters timeut_ms=<millisecnds> If a respnse hasn t been returned within the number f millisecnds specified then the request will be halted and a timeut message returned. structured_respnse=[1 0] (1 by default) If this is set t 0 nly the text_result and status fields will be returned regardless f what parameters are set. questin_entities=[1 0] (1 by default) If we can identify an entity f interest in the questin then we ll return that in additin t the answer. E.g. the questin Wh wrte the Da Vinci Cde? will return [the da vinci cde] as well as the answer [dan brwn]. retranslate=[1 0] (0 by default) This will utput True Knwledge s interpretatin f what was asked and return it within the <tk:retranslatin> tag. bject_metadata=wikipedia,fficial,image64,image128,image1 50,imageprfile (wikipedia, fficial and image150 set by default) This parameter gives the ptin f including useful metadata with yur answer. wikipedia This will include the URL f the wikipedia page related t each result (if we knw f ne). fficial This will include the URL f the fficial website f each result (if we knw f ne), e.g. if the questin is Wh wrte the Da Vinci Cde? then the respnse will include the URL: assciated with the [dan brwn] entity. 5

6 image64 Returns a thumbnail image assciated with each result (if we have ne) that is cnstrained t a bunding bx f 64x64 pixels. image128 Returns a thumbnail image assciated with each result (if we have ne) that is cnstrained t a bunding bx f 128x128 pixels. image150 Returns a thumbnail image assciated with each result (if we have ne) that is cnstrained t a bunding bx f 150x150 pixels. imageprfile Returns an image assciated with each result (if we have ne) that is cnstrained t a bunding bx f 225 pixels wide x 600 pixels high. 3.3 Perfrmance Fr maximum perfrmance set structured_respnse t 0, this will nly return the <tk:status> and <tk:text_result> fields. If yu want yur answer s entities but nt yur questin s entities then set questin_entities t 0. The fewer parameters yu set the quicker yu will receive yur respnse. Fr example, setting bject_metadata t return the URL f every image size available will take slightly lnger than just returning ne image URL. 3.4 Direct Answer API hell wrld The Direct Answer API hell wrld is sending a request fr the time in Chicag and getting Chicag s current lcal time back alng with a link t the Wikipedia page fr Chicag and a thumbnail pht f the Chicag skyline HTTP request questin=what's+the+time+in+chicag &bject_metadata=image128,wikipedia &api_accunt_id=[username] &api_passwrd=[passwrd] 6

7 3.4.2 XML respnse <?xml versin="1.0" encding="utf-8"?> <tk:respnse xmlns:tk= xmlns=" understd="true" answered="true" type="direct_answer"> <tk:status>cmpleteness unknwn</tk:status> <tk:text_result>march 16th 2009, 10:57:30 CDT</tk:text_result> <tk:structured_result> <tk:result> <tk:bject> <tk:id>[lcal timepint: [timepint: ["2009/3/16/10/57/30"]]; [central daylight time]]</tk:id> </tk:bject> </tk:result> <tk:questin_entities> <tk:bject> <tk:id>[chicag]</tk:id> <tk:metadata parameter="image128"> wledge.cm/images/thumbs/128/128/ _2600x1500_chicag_lake_skyline.jpg< /tk:metadata> <tk:metadata parameter="wikipedia"> dia.rg/wiki/chicag</tk:metadata> </tk:bject> </tk:questin_entities> </tk:structured_result> <tk:tk_questin_url> 's_the_time_in_chicag</tk:tk_questin_url> </tk:respnse> The XML explained XML field <tk:respnse xmlns:tk=" xmlns=" l" understd="true" Descriptin This is the cntainer field fr the entire direct answer API respnse. There are tw attributes f interest in this XML tag and they are the understd and answered attributes. understd means we have understd the questin 7

8 answered="true" type="direct_answer"> <tk:status> <tk:text_result> <tk:structured_result> <tk:result> <tk:questin_entities> <tk:bject> <tk:id> <tk:metadata parameter="image128"> <tk:metadata parameter="wikipedia"> <tk:tk_questin_url> and answered means we have answered the questin. This returns either yes, n, cmplete r cmpleteness unknwn. Fr yes/n questins the respnse is self explanatry. If the questin is nt yes/n the status field will return cmplete if we knw that we have the cmplete answer (e.g. Wh is a child f President Mnre is status cmplete because we knw that we knw abut all f President Mnre s children), in mst cases hwever the respnse will be cmpleteness unknwn as the majrity f the time we dn t knw if we have a cmplete answer. This field cntains the main text answer t the questin. This is the cntainer field fr the structured results (images, links, etc). This field cntains the structured versin f the answer. This is the cntainer field fr questin entities (entities that appeared in the questin). This is a cntainer field fr each questin entity. This field cntains the True Knwledge ID f a questin entity. This field cntains the URL f a thumbnail image f a questin entity (in this case the thumbnail will have been scaled t fit in a 128x128 pixel bunding bx). This field cntains a questin entity s Wikipedia page URL. This is the permanent URL t the questin and answer page n trueknwledge.cm 8

9 4 Query API The Query API allws autmated systems t bypass ur natural language translatin system and directly query the knwledge base using a simple query language. Fr mre infrmatin n writing True Knwledge queries visit: Required parameters api_accunt_id=[api_username] passwrd=[passwrd] query_text=[url encded true knwledge query] e.g. query+result%0a%5b% %22%5d+%5bcan+den te%5d+number%0aresult+%5bis+the+gegraphical+area+f r+the+telephne+number%5d+number 4.2 Optinal parameters mde=[establish full] (establish by default) establish respnds with either yes r n/unknwn fr truth queries ( yes/n questins), whereas full respnds with either yes, n, r unknwn. Fr mst queries establish will be sufficient. translate_answers=[1 0] (0 by default) This will return the answer in a frm that is easy fr peple t read as well as the machine readable frmat. 4.3 Query API hell wrld The QUERY API hell wrld is sending a request fr the gegraphical lcatin that matches the telephne number and getting the respnse [the cambridge telephne cde area] HTTP request query=query+bj%0a%5b% %22%5d+%5bcan+dente%5 D+number%0Abj+%5Bis+the+gegraphical+area+fr+the+telephne+ number%5d+number &api_accunt_id=[username] &api_passwrd=[passwrd] 9

10 4.3.2 XML respnse <?xml versin="1.0" encding="utf-8"?> <tk:respnse xmlns:tk=" xmlns=" type="query"> <tk:status>cmpleteness unknwn</tk:status> <tk:num_results>3</tk:num_results> <tk:result> <tk:variable name="bj"> <tk:id>[the cambridge telephne cde area]</tk:id> </tk:variable> </tk:result> <tk:result> <tk:variable name="bj"> <tk:id>[cambridgeshire]</tk:id> </tk:variable> </tk:result> <tk:result> <tk:variable name="bj"> <tk:id>[the united kingdm and the channel islands]</tk:id> </tk:variable> </tk:result> </tk:respnse> The XML explained XML field <tk:respnse xmlns:tk=" xmlns=" l" type="query"> <tk:status> Descriptin tk:respnse is the cntainer field fr the entire query api respnse. This returns either yes, n, cmplete r cmpleteness unknwn. Fr yes/n questins the respnse is self explanatry. If the questin is nt yes/n the status field will return cmplete if we knw that we have the cmplete answer (e.g. query x x [is a child f] [president james mnre] is status cmplete because we knw that we knw abut all f President Mnre s children), in mst cases hwever the respnse will be 10

11 <tk:num_results> <tk:result> <tk:variable name="bj"> <tk:id> cmpleteness unknwn as the majrity f the time we dn t knw if we have a cmplete answer. The number f results in the respnse. The cntainer field fr each result. This is the variable name that was queried fr and cntains the result fr that variable. The True Knwledge ID f the entity. 11

12 5 Crediting True Knwledge With a free API accunt, users f ur API services must credit True Knwledge and place a prminent link back t ur site: With the direct answer service the questin URL returned in the tk_questin_url tag shuld be used. If yu wish t avid this requirement, please cntact us at partners@trueknwledge.cm If yu want yu can use this image as yur credit link: This image can be fund here: Fr example yur credit may lk like this when using the direct answer service: <a href= title= What is the capital f France ><img src= alt= Pwered by True Knwledge ></a> 12

13 2009 True Knwledge Ltd. All rights reserved. This manual, as well as the sftware described in it, is prvided under license and may be used r cpied nly in accrdance with the terms f such licence. The cntent f this manual is prvided fr infrmatinal use nly, is subject t change withut ntice, and shuld nt be cnstrued as a cmmitment by True Knwledge Limited. True Knwledge Limited assumes n respnsibility r liability fr any errrs r inaccuracies that may appear in this manual. Except as permitted by such licence, n part f this publicatin may be reprduced, stred in a retrieval system, r transmitted, in any frm r by any means, electrnic, mechanical, recrding, r therwise, withut the prir written permissin f True Knwledge Limited. 13