API Guide
Table f Cntents 1 Intrductin... 3 2 Cnnecting t the API... 4 2.1 HTTP request syntax... 4 2.2 API release versins... 4 3 Direct Answer API... 5 3.1 Required parameters... 5 3.2 Optinal parameters... 5 3.3 Perfrmance... 6 3.4 Direct Answer API hell wrld... 6 3.4.1 HTTP request... 6 3.4.2 XML respnse... 7 3.4.3 The XML explained... 7 4 Query API... 9 4.1 Required parameters... 9 4.2 Optinal parameters... 9 4.3 Query API hell wrld... 9 4.3.1 HTTP request... 9 4.3.2 XML respnse... 10 4.3.3 The XML explained... 10 5 Crediting True Knwledge... 12
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
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: https://<hst>/<service_name>?<parameters> <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: http://api.trueknwledge.cm/direct_answer/?questin=list+f+james+b 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: https://api.trueknwledge.cm/<service_name>/stable?<parameters> If n versin is specified then stable is the default ptin, s the abve URL is the same as: https://api.trueknwledge.cm/<service_name>?<paramaters> If yu want t use the latest (but nt necessarily stable) versin f the API this is the syntax t use: https://api.trueknwledge.cm/<service_name>/latest?<parameters> If yu want t use a specific versin f the API this is the syntax t use: https://api.trueknwledge.cm/<service>/<versin_number>?<parameters > 4
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: http://www.danbrwn.cm/ assciated with the [dan brwn] entity. 5
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. 3.4.1 HTTP request https://api.trueknwledge.cm/direct_answer? questin=what's+the+time+in+chicag &bject_metadata=image128,wikipedia &api_accunt_id=[username] &api_passwrd=[passwrd] 6
3.4.2 XML respnse <?xml versin="1.0" encding="utf-8"?> <tk:respnse xmlns:tk=http://www.trueknwledge.cm/ns/kengine xmlns="http://www.w3.rg/1999/xhtml" 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">http://www.truekn wledge.cm/images/thumbs/128/128/2004-07- 14_2600x1500_chicag_lake_skyline.jpg< /tk:metadata> <tk:metadata parameter="wikipedia">http://en.wikipe dia.rg/wiki/chicag</tk:metadata> </tk:bject> </tk:questin_entities> </tk:structured_result> <tk:tk_questin_url>http://www.trueknwledge.cm/q/what 's_the_time_in_chicag</tk:tk_questin_url> </tk:respnse> 3.4.3 The XML explained XML field <tk:respnse xmlns:tk="http://www.trueknwledge.cm/ns/kengine" xmlns="http://www.w3.rg/1999/xhtm 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
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
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: http://www.trueknwledge.cm/dcs/query_language/ 4.1 Required parameters api_accunt_id=[api_username] passwrd=[passwrd] query_text=[url encded true knwledge query] e.g. query+result%0a%5b%22+44+1223+323382%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 +44.1223.323382 and getting the respnse [the cambridge telephne cde area]. 4.3.1 HTTP request https://api.trueknwledge.cm/query? query=query+bj%0a%5b%22+44+1223+323382%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
4.3.2 XML respnse <?xml versin="1.0" encding="utf-8"?> <tk:respnse xmlns:tk="http://www.trueknwledge.cm/ns/kengine" xmlns="http://www.w3.rg/1999/xhtml" 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> 4.3.3 The XML explained XML field <tk:respnse xmlns:tk="http://www.trueknwledge.cm/ns/kengine" xmlns="http://www.w3.rg/1999/xhtm 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
<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
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: http://www.trueknwledge.cm/. 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: http://www.trueknwledge.cm/dwnlads/pwered_by_tk.png Fr example yur credit may lk like this when using the direct answer service: <a href= http://www.trueknwledge.cm/q/what_is_the_capital_f_france title= What is the capital f France ><img src= http://www.trueknwledge.cm/dwnlads/pwered_by_tk.png alt= Pwered by True Knwledge ></a> 12
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