True Knowledge - Blog

Calling the True Knowledge API using Javascript

Pierre Far — Tue, 22 Sep 2009 16:20:33 +0100

A very common question we receive from our API users is how to call the True Knowledge API using Javascript/AJAX.

The short answer: you don't call the API directly using Javascript, but you can call it indirectly. This post explains why and how to do so.

Why not

The reason for not calling the API directly is because the URL call contains your API account credentials, namely your username and API "password" (the API key if you will). If you embed this information into a web page so that it can call the API directly using Javascript, you will be exposing these credentials: anyone can then find your account details.

Another complication: our API currently outputs only XML, which is not the most Javascript-friendly output.

Solution

So what to do? Proxy the calls via a server-side script on your website. The server-side script, would be written in PHP or Python or your programming language of choice. It will accept, via a query string variable, the actual search, process it, and then return the results to the Javascript.

In detail:

Create the server side-script; let's call this script tk.php and let's say it is hosted on your website at http://example.com/tk.php. We'll talk about the exact contents of tk.php in a second.
Using jQuery or any other way to do the AJAX call, request tk.php. For example, if the Javascript wants to call the True Knowledge API to ask "what is the capital of France", the AJAX call could be to:
http://example.com/tk.php?input=what+is+the+capital+of+france
Here, we're using the query string variable "input" to pass the search to tk.php
Wait for tk.php to call the True Knowledge API and display its output in the page. The exact details of this vary by how you are doing the AJAX call, and most Javascript frameworks like jQuery and Prototype give you an easy way to embed AJAX output into a web page.

What happens on the server

We already have an excellent starting point for tk.php: it is the da.php example in our API PHP library. What we want here is an even simpler version of this file, so we're going to strip it down.

The da.php file calls our Direct Answer API service, which is the easiest to work with for this example. You can certainly build more complicated API calls using a True Knowledge Query API call as detailed in the tkquery.php file in the library examples folder.

The first task is to get rid of the HTML page formatting because the output is going to be embedded into a pre-existing HTML page.

Secondly, you need to decide if you would like the AJAX output to (potentially) show any errors. In the code below, I've commented out anything that does not display a search result.

You'll notice that the code below is printing everything the API returned without any real formatting and basic HTML markup. Of course customize this to your needs.

And with all this said, below is the full code for the tk.php proxy for your AJAX calls.

<?php
define('API_DIRECTORY', dirname(__FILE__) . '/..');
define('API_ACCOUNT_ID', '');
define('API_ACCOUNT_PW', '');

if(isset($_GET['input']))
{
	//You should sanitize the input as necessary for your application.
	$query = $_GET['input'];
}
if(is_string($query) && strlen($query) > 0)
{
	require_once(API_DIRECTORY.'/api.php');
	$request = new KnowledgeEngineDirectAnswerRequest(); 
	
	$request->setAccountId(API_ACCOUNT_ID);
	$request->setAccountPassword(API_ACCOUNT_PW);

	try {
		$request->setQuery($query);
		$response = $request->execute();
		if(strlen($response->getErrorCode()) > 0)
    {
			//NOTE: for this example, we are hiding any errors
			//echo "<p>Error for query (".$query."):</p>";
			//echo "<p>".$response->getErrorCode()." ".$response->getErrorMessage()."</p>";
    } else {
			echo "<p>Answer for ".$query."</p>";
      echo "<p>".$response->getTextResult()."</p><hr/>";
			if ($results = $response->getResults())
      {
				foreach($results as $result)
        {
					echo "<p>True Knowledge ID: ".$result->getId()."</p>";
					if($result->getOfficialWebSite())
          {
						echo "<p>Official website: <a href=\"".$result->getOfficialWebSite()."\">".$result->getOfficialWebSite()."</a></p>";
          }
					if($result->getWikiPage())
          {
						echo "<p>Wikipedia page: <a href=\"".$result->getWikiPage()."\">".$result->getWikiPage()."</a></p>";
          }
					if($result->getImage())
          {
						echo "<p>Image: <img src=\"".$result->getImage()."\" /></p>";
          }
					echo "<hr/>";
        }
  		}
		}
	}
	catch ( Exception $ex)
  {
		//NOTE: for this example, we are hiding any errors
		//echo $ex->getMessage();
  }
}

True Knowledge Partners with Omgili

Pierre Far — Fri, 11 Sep 2009 12:02:02 +0100

We are really pleased to let everyone know about another exciting True Knowledge API partner, Omgili.

Omgili, a VC backed search start-up that focuses on “many to many” user generated content platforms, such as forums, discussion groups, answer boards and other sources, has integrated True Knowledge results into their Google@Omgili service. It is a fantastic example of how True Knowledge can be combined with other search methods to help provide a truly superior search experience, as shown in the example search for "president of france in 2009" screenshot below.

Google@Omgili brings together knowledge-based responses powered by True Knowledge and Google search results and it combines theses with their ability to find forum discussions about the results Google returns. With this combination, you can get direct answers to your questions, and you can find people interested in the same topics as you as well as finding more in depth discussions about the subject you are researching.

Organizing the World's Knowledge: The True Knowledge Ontology - Part I

Pierre Far — Thu, 10 Sep 2009 16:11:12 +0100

At the heart of the True Knowledge semantic technology is our ontology. Our ontology describes a tree-like structure of classes, and every entity fits into this tree.

In this post I'm going to explain a bit more about how we structure the world's information and how you can tap into this structure using our API.

But first, some theory. Don't skip it because it directly affects how you query the True Knowledge API!

What is a Class?

The easiest way to explain a class is take a real world example. Below is an image showing the class [book].

In our ontology, the class called [book] describes all books. It is the collection of all books that we know about, and it will be the home of all books we don't know about when they are added. All books have similar properties and attributes, and all of them can be described in similar terms: If I ask you to imagine what a book is, your mind will picture something similar to what other people imagine a book to be. In short, if you can say "This is a <something>", that something is a class.

We know there are different types of books, like novels, cookbooks, art books, textbooks, science books, science fiction books, etc. These are all subclasses of the class [book]. A subclass is a more specific class, and so is lower down in the ontology tree.

Of course it works the other way too: a more general class is a parent class. So the parent class of [science book] and [cookbook] is [book]. The class [book] itself has two parent classes, [written publication] and [source of knowledge]. The class [written publication] has other subclasses such as [comic], [issue of a periodical], etc.

You can easily browse our ontology by looking at the profiles of a class and clicking through to parents and children. Here are profiles for some of the classes mentioned above:

Instances of Classes

So far we've been talking about classes which are collections ordered in the ontology tree. So what about members of these classes? How does True Knowledge handle specific books like The Da Vinci Code?

Each member of a class, for example each book, is an instance of that class. So [the da vinci code] is an instance of [book]. Likewise, [dune] is also an instance of [book].

API Queries

To test these queries, you will need to use our API library. Details of our new API library are in this previous blog post.

You can get all subclasses of books that we know about with this query:


query bookclass

bookclass [is a subclass of] [book]

The following TK Query gets a list of novels from True Knowledge:


query novel

novel [is an instance of] [novel]

The query asks for a variable called "novel" which satisfies the relation "[is an instance of]" for the True Knowledge ID of the class [novel].

Finally, you can tap into the power of having a structured ontology tree by getting a list of books, novels and everything else, with this query:


query book

book [is an instance of] [book]

If you look through the list of results returned by the books query and compare it to the novels query results, you'll see overlap. This is because all instances of the class [novel] are also instances of the class [book] because [novel] is a subclass of [book]. You can go up the tree more and ask for all instances of the class [written publication], which will get you all books (including novels) and other publications.

A Question of Time: Answers that May Change

Pierre Far — Fri, 04 Sep 2009 16:56:48 +0100

One of the key concepts with our semantic technology is answering questions whose answers vary depending on which time point the query refers to. Today, I'd like to explore the issues around such queries to help you get the most out of our API when you use it.

Modeling Time

Broadly, our system supports four types of such queries, which we call temporal classes:

Permanent, i.e. never changes. For example, "When is Elvis Presley's birthday?".
Transient, i.e. true for a period of time but not necessarily true before or after it. For example, holders of political office (Who is the Prime Minister of the UK?) and other occupations, marital status (Is Tom Cruise married?), country population, addresses (a company's HQ address for example) and more.
Dynamic, i.e. changing very quickly. A good example is stock market data, exchange rates. These change too fast to have representations about periods of time and often require an external source.
Unrevertable, i.e. Once the fact becomes true, it cannot change. Facts involving the attribute [dead] are an example. e.g. Compare Is Elvis Presley alive? and Was Elvis Presley alive in 1970?.

True Knowledge models some facts as transient temporal facts even if they are so slow changing that people think of them as permanent. A good example is political geography where the borders can (and do) change in time, but at any given moment people think of them as permanent.

There is one more temporal class, what we call "true now". For this class of facts, we simply represent that the knowledge is true at the moment the platform answers the query and don't represent historical information. This is commonly used as a convenience for lexical knowledge like facts which use the [can denote] relation.

Using our API

So now you know about how to think about time in relation to knowledge, let's look at some queries.

You will need the True Knowledge API library which we talked about last time.

In the Direct Answer API mode, you simply query in natural language. The examples above are a good start, and here is one more: Who was prime minister of the UK in 1969?

To get you starting constructing True Knowledge Queries, as you would in an application, let's translate the above examples to TK Queries.

Poland and the EU

Let's look at these two queries:

query f: [poland] [is a member of] [the european union] f [applies at timepoint] [timepoint: ["2000"]]
query f: [poland] [is a member of] [the european union] f [applies at timepoint] [timepoint: ["2008"]]

We know that Poland joined the EU on 1st of May 2004, and so the queries above should, respectively, return a No and a Yes answer.

These queries also introduce three new things to learn:

The "f:" notation: This means "look up the fact ID" and you describe the fact after the colon. The f here is used to bind the variable f to the fact ID, and you can name the variable anything you want. Once bound, you can use the variable as usual in the query. This notation is the full notation for representing a fact including the id and the three entities, and the fact ID portion is optional. Missing it out, like all the queries from our previous post, still works.
The [applies at timepoint] relation. We talked about relationships last time, and today we're using a new relation to specify when this fact applies.
The notation for timepoints. It's the common notation of the format yyyy/mm/dd. For practice, try the two queries above with timepoints just before 1st of May 2004 (say 30th of April) and just after (2nd of May).

To generate the current timepoint (now) you can use a query line like the following:

[current time] [applies to] now This puts the time the query is executed into the variable now so to ask whether Poland is currently in the EU the query is:

query [current time] [applies to] now f: [poland] [is a member of] [the european union] f [applies at timepoint] now

To ask "Who is the president of the US?", the query is:

query p [current time] [applies to] now f: p [is the president of] [the united states of america] f [applies at timepoint] now



Unrevertable Facts and Time Periods: Johnny Cash
This is similar to the queries above, but about unrevertable facts:

query

f: [alive] [applies to] [johnny cash]

f [applies at timepoint] [timepoint: ["2009"]]
query

f: [alive] [applies to] [johnny cash]

f [applies at timepoint] [timepoint: ["2000"]]

Johnny Cash gives us another great example for time queries. To find out when he was alive, i.e. the time period between his birth day and his death, try this query:

query lifespan

f: [alive] [applies to] [johnny cash]

f [applies for timeperiod] lifespan
Note another new relation, [applies for timeperiod], which is similar to the [applies at timepoint] relation we saw above.

Conclusion
And so now you know how we work with time at True Knowledge and how to access time-based facts using our API. Download our API library and play with the queries above to see how it works. If you have any questions, please post in the comments below.



New PHP API Library and Example Code
Pierre Far — Tue, 25 Aug 2009 16:47:42 +0100
The True Knowledge API is a very easy way for applications to tap into our semantic technology.

To help developers start, we've had a PHP library that wraps up the mundane details of accessing our API. The library has served us well and today we're announcing a beta version that is easier to use: The new library helps you send queries and get their results using simpler code. Also, the new library is easier to understand if you want to dig into the details of what's going on with each call.

Two APIs
Our API gives you two different modes of interaction:

The Direct Answer (DA) mode where you query in natural language and get the answer(s) back. For example, you can ask "who was born on october 25?" and you will get a list of people that True Knowledge knows were born then.
The True Knowledge Query (TK Query) mode where you use our internal query language to get the answers you want.

For equivalent searches, the DA is slower because it has to process your natural language query and translate it into a TK Query but it's simpler to use and reflects how users actually search.

Getting Started
It's easy to get started:

Register for an API account, which is different from your True Knowledge account (if you have one).
Download the new beta version of the PHP library and look at the included examples.


Example Code & Sandbox
Included in the PHP library download is an examples directory with two files called da.php and tkquery.php that you can use to build on.
You need to specify your API account ID and password (the equivalent of an API key) near the top of the example files. It's a pair of define() statements.
If you want a lower-level look at our API, the API home page also has a sandbox for you to test our queries and see the raw query URLs and XML being returned.

DA Query Examples
DA queries are very easy: your query is how you would phrase it in English. Some examples:

Where can I buy a pillow in Glasgow? This gives you results like our local product search engine.
List US states. This returns a list of the US states.
Is the Eiffel Tower older than the Statue of Liberty? This demonstrates the inference (deduction) ability of True Knowledge's semantic technology, and it gives you a direct simple answer: No.


True Knowledge Query Examples
True Knowledge Queries (TK Queries) are written in the internal query language. Think of it as SQL for knowledge.
When I was learning TK Queries, I understood them best when I realized they're a bit like logic and algebra. A query starts by saying "I want to know about something" and then goes on to describe how to derive the answer in a logical manner.
For example:

query x

x [is an instance of] [james bond movie]

The first line says "I want to know about something I'm calling x". You can call your variable anything you want; a more apt name here is 'movie' because of the second line. Just like other programming languages, it's good to pick sensible variable names!
The second line describes what x is: it is an instance of a class of objects labeled "james bond movie". Because True Knowledge stores knowledge in a structured and hierarchical manner, all James Bond movies are a type of one class, and so we're asking for every member of that class.
Notice the use of "[is an instance of]". This is what we call a relation and it is one type of relationship we know about. A relationship links two bits of knowledge together. In our example, we're linking the variable 'x' to the class [james bond movie].

True Knowledge understands many relations, and the trick is to find one that will solve your query. Over the next few weeks, we'll be writing more about how to do TK Queries and diving into their details and doing more complex examples.

Another example:

query place, place_info

["chicago"] [can denote] place /r

place [is an instance of] [geographical area]

place [uniquely translates as] place_info
This query breaks down as follows:

We're asking True Knowledge for two variables: something we're calling 'place' and another we're calling 'place_info'.
This thing called 'place' we are interested can be referred to as "Chicago". The /r tells the TK Query to ignore rare and less common translations of the query. So in this case, we're really interested in the famous Chicago, not any other town also called Chicago. For fun, try your queries both with and without the /r.
In the third line, we explain more about 'place' saying it belongs to a class of things we call 'geographical area's. The second and third lines together uniquely identify the well known city in Illinois.
Finally we ask for a unique (long) "noun phrases" that describes the 'place' we just found. True Knowledge stores a phrase (called a URS) for each object we have in our database, and so asking for it gives you more content to add to your query results explaining to the user what True Knowledge just returned.


Feedback and Getting More Help
As this is a beta version of the API library, we would love your feedback in how it's working (or not) for you. We are actively developing this library as a replacement for the old one, and so your feedback will directly influence this development!

The easiest way to give us feedback is to use the API support forums, which True Knowledge employees constantly read.

The forums are also the best place to get help directly from us and other API users.

To access the forums, you will need to sign in with your True Knowledge account (register here), which is different from your API account.

Don't forget to subscribe to this blog too to stay updated with API news and examples in the future!