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!
Comments