Kngine Webservice API Reference

API Version 1.0 Documentation



Content

Obtaining an AppID »
Make a request »
Working with results »
Simple results »



Introduction

The Kngine Webservice API provides a API allowing the question answering capabilities of Kngine to be integrated into web, mobile, desktop, and enterprise applications.

The API allows clients to submit free-form queries, and for the computed results to be returned in a variety of formats. The API is implemented in a standard REST protocol using HTTP GET requests. Each result is returned as a descriptive JSON structure wrapping the requested content format.

Use of the Kngine Webservice API is subject to the API Terms of Use, which can be found at Kngine.com/api/TermsOfUse.html.



Obtaining an API Key

The API Key is a string that identifies your application, and it must be supplied in all calls to the Kngine API.

Curretly you can obtaining API Key by contacting Kngine at business@kngine.com, in near future we will open the registeration for Kngine API account.



Make a request

Here is an example search request:

GET http://www.Kngine.com/SearchAPI1.ashx?key={INSERT-YOUR-KEY}&q={Question-Or-Query}


Two query parameters are required with each search request:

  1. API Key. Use the key query parameter to identify your application
  2. Query. Use the q query parameter to specify your query.


Optional paramters:

  1. Target language. Use lang query parameter to specify target language of the answer. If you didn't specify target language result will be in same language as query, Kngine currently support English, Spanish, German and Arabic
  2. Location. Use lat and long query parameter to specify location. This parameter only used for location related queries.



Working with results

The result of a call to the API is always an JSON document. The JSON document consist of three element:

  1. Status. String contain the status of the query. The value of the status could be 'Ok', 'Empty', 'Error' or 'Access Denial'.
  2. Query. Which is object include information about submitted query in two string fields, 'Query' and 'QueryLanguage', which include the sent query and the detected query language respectively.
  3. Result. Which is object include the query result, this object have two fields 'TextAnswer' which include the answer as a text if possible ('TextAnswer' field was activated by April 3, 2013) and 'Items' which is array of rich answer items.


Simple query

A simple API call to retrieve output for the query "GEP of Germany" would look like this:

GET http://api.kngine.com/searchapi1.ashx?q=GDP%20of%20Germany&key={INSERT-YOUR-KEY}


Resuts

{
    "Status": "Ok",
    "Query": {
        "Query": "GDP of Germany",
        "Language": "EN"
    },
    "Result": {
        "TextAnswer": null,
        "Items": [
            {
                "Type": "list",
                "SubType": null,
                "Title": null,
                "Items": [
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp (current us$)",
                        "Value": "3,652.824 Billion  US$ (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp growth (annual %)",
                        "Value": "1.3 (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp (purchasing power parity)",
                        "Value": "2,807 Billion  US$ (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp (official exchange rate)",
                        "Value": "3,322 Billion (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp per capita (ppp)",
                        "Value": "34,100  US$ (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "GDP Composition By Section",
                        "Value": "Agriculture of gdp: 0.92 (2007)\r\nIndustry of gdp: 30.09 (2007)\r\nServices of gdp: 68.99 (2007)\r\n",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp (official exchange rate)",
                        "Value": "3,322 Billion (2008)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp - per capita (ppp)",
                        "Value": "34,100  US$",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Gdp (purchasing power parity)",
                        "Value": "2,807 Billion  US$ (2008)",
                        "ValueURL": null
                    }
                ]
            },
            {
                "Type": "entity",
                "SubType": null,
                "Title": "Germany",
                "Abstract": "Germany, officially the Federal Republic of Germany, is a country in Central Europe. It is bordered to the north by the North Sea, Denmark, and the Baltic Sea; to the east by Poland and the Czech Republic; to the south by Austria and Switzerland; and to the west by France, Luxembourg, Belgium, and the Netherlands. The territory of Germany covers 357,021 km² and is influenced by a temperate seasonal climate. With over 82 million inhabitants, it has the largest population of any member state of the European Union and is home to the third-largest number of international migrants worldwide. A region named Germania inhabited by several Germanic peoples has been known and documented before 100 AD. ",
                "ImageURL": "https://www.googleapis.com/freebase/v1/image/guid/9202a8c04000641f80000000000190af?key=AIzaSyCQVC9yA72POMg2VjiQhSJQQP1nf3ToZTs&maxwidth=160&maxheight=160",
                "Url": null,
                "Attributes": [
                    {
                        "Type": "keyValueText",
                        "Key": "Capital",
                        "Value": "Berlin",
                        "ValueURL": "http://api.Kngine.com/SearchAPI1.ashx?q=Berlin&conceptId="
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Total area",
                        "Value": "357,022 sq km (2009)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Land area",
                        "Value": "348,672 sq km (2009)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Water area",
                        "Value": "8,350 sq km (2009)",
                        "ValueURL": null
                    },
                    {
                        "Type": "keyValueText",
                        "Key": "Population",
                        "Value": "82.14 Million (2008)",
                        "ValueURL": null
                    }
                ]
            }
        ]
    }
}

The results are separated inside array called 'Items'. Each item represent a complete result section that we recommend to render in separated container/section. All items have string field named 'Type' which determine the type of the object and its internal structure. The following is detailed information about every type:

text

The simplest result item type, it's contain one field named 'Content' that include the answer


keyValueText

This type is very common way to describe attribute, such as 'population : 81 Million', it's contain three fields named 'Key', 'Value' and 'ValueURL'


keyValuesText

This type is very common way to describe attribute that have multiple values, such as 'Industry : Software, Search Engine', it's contain two fields named 'Key', 'Values' which is list of tuple contains 'Value' and 'ValueURL'


url

This type used only to link another entity, search result, or external page, it have four fields 'Title', 'URL', 'ThumbnailImageURL' and 'HTMLContent'


html

We use this type only if the answer can't be represented using our standard object-orinted manner, object of this type have two fields 'Title' and 'HTML'


entity

Object of this type used to represent entities, such as: Movies, Person, etc. This type have six fields:

Name

Type

Notes

Title

string

 

ImageURL

string

 

URL

string

If the 'URL' field is present, that means that this entity is searchable. For example if you was searching about 'Founders of Intel' you will receive array of entities, the entities that have ‘URL’ is the one that searchable.

Abstract

string

 

Attributes

Array of objects that could be ‘Text’, ‘keyValueText’, ‘keyValuesText’

 

SubType

string

SubType field used to identify the type of the entity, which can make the client visualize the entity in special way or do extra action based on the entity type

 

Currently the possible SubTypes are:: ‘flightStatus’, ‘actor’, ‘movie’, ‘stockPrice

 

* note: this field is in experiment stage


businessEntity

Object of this type used to represent business entities, such as: Restaurant, Theater, etc. This type is very similar to entity, but it have five more fields 'Address', 'Phone', 'Lat', 'Lng', and 'OtherURLs'. The 'OtherURLs' is list of object of type 'url' described above.


image

Object of this type used to represent image, this object have four fields named 'Title', 'ImageURL', 'ThumbnailURL' and 'PageURL'


map

Object of this type used to represent map points, this object have one field named 'Pins' that is array of object have the following fields: 'Title', 'Lat' and 'Lng'


weather

Object of this type used to represent weather information, this object have three fields named 'Location', 'Current' and 'Forcast'.
'Current' field have the current weather status, and it's have the following fields: 'Temprature', 'Status', 'WindSpeed', 'WindDirection', 'Humidity', 'IsNight' and 'IconURL'
'Forcast' field is array that have the future forcast for few days, and it have the following fields: 'Day', 'Hi', 'Lo', 'Status' and 'IconURL'


list

This is very common type, object of this type used to represent set of objects together like images, text, keyValueText, etc.
Object of this type have three fields named 'Title', 'Items' and 'SubType'. The value of 'SubType' specify the type of the items in the array, currently it could be:

  • businesses

  • webResults

  • images

  • videos

The field 'Items' is array and it contiain any of the items mentioned above, except 'map' and 'weather'



Simple results

We prepared a package of several simple results at http://Kngine.com/api/SimpleResults.zip that you can download it and see how the result is composed. Also download Kngine for iOS or Android today to see how this results rendered.
Also this C# library have all the classes.




Kngine - Your new digital assistant
© 2012 Kngine | Contact Us | Feedback | Privacy