Developer Center

Using the API

Just after you start a cloud search service on Kimola, you will have an API key to use all features over HTTP. When your client application makes an HTTP request, the API responses the request via JSON data-interchange format. Thus, you can deserialize JSON responses to logical objects in your application easily.

1. Definitions

The terms and definitions used throughout this document is listed below

API Key - An alpha-numeric string is used to identify the user making the request. API key must be the first part of the request URL.

Resource - A mapping between an URL path and a data type. The resource defines a list of fields that will be returned within the response. Search resources are limited to returning no more than 100 results per each request. Subsequent queries can be made to continue fetching more results.

2. Making Requests

Our main goal is to make it easy to access your data. That's why we've adopted a RESTful style of query access. As long as you can make a web request, you can access your data.

Each request is made to a specific resource. A resource defines the type of the object that would be processed.

A request to a Resource contains an API key, usually a resource name and optionally a resource identifier. For example, the following URL would make a request to retrieve all the PartSpaces with a given API in JSON format:

http://444.kimola.com/api/{key}/part-space

That URL becomes easier to understand if broken apart. The "api/{key}/part-space/" path refers to the /part-space/ resource of the database belonged to {key}.

3. Handling Responses

Every response has some common status codes that can be handled accordingly. There is also an explanation about the error. By using this status codes, you can determine whether the the request was processed successfully or not. The following table describes each status code you can get.

4. Methods

You can make raw HTTP Requests or use a client library for your development environment. Below is the libraries you can use including official .NET library:

The API supports nine essential operations currently:

• Index Document
• Batch Index Document
• UnIndex Document
• Truncate Documents
• Get Part Spaces
• Delete Part Space
• Search
• Get Phrases
• Get Suggestions

The methods served by Kimola Cloud API are explained in detailed below by indicating the return types or possible status codes.

4.1. Index Document

The API expects a serialized document object within the request body. The document sent will be queued, then indexed as soon as possible. If you get 202 status code, that means everything went well and your document will be indexed with the given API key.

Request (POST)

http://444.kimola.com/api/{key}/document

Sample document object:

{
    "Url": "http://www.yourdomain/article/wozniaks-travel-backpack",
    "APIKey": "xyz123",
    "PartSpace": "technology",
    "Title": "You’ll Never Guess What’s in Steve Wozniak’s Backpack",
    "Content": "\"Sometimes TSA takes a long time unpacking it,\" Wozniak says. \"A couple of times they asked me to take out everything electronic and I asked for seven bins, all of which I filled (only 2 half-size), plus my MacBook Pro, plus the bag. All of that through the X-ray machine. Then repack it.\"",
    "DocumentDate": "2012-06-15T13:00:00",
    "Culture": "en-US"
}

Possible Responses: 202 (Accepted)

Possible error status codes special for this operation:

• CodeExplanation
• 412The request body must contain a HarisDocument
• 412Part Space can not be null or emptry or longer than 16 characters
• 412Url can not be null or empty
• 412Url can not be longer than 250 characters
• 412Url must be in absolute uri format e.g.; file://C:\\my-file.pdf, http://www.my-site.com/my-page.html
• 412Culture code must be in correct format e.g.; en, en-US, en-IE, tr, tr-TR
• 412Given document date is out of range: {documentDate}

4.2. Batch Index Documents

The API expects a serialized document array within the request body. The document sent will be queued, then indexed as soon as possible. If you get 202 status code, that means everything went well and your documents will be indexed with the given API key.

Request (POST)

http://444.kimola.com/api/{key}/documents

Sample document array:

{
    "Url": "http://www.yourdomain/article/wozniaks-travel-backpack",
    "APIKey": "xyz123",
    "PartSpace": "technology",
    "Title": "You’ll Never Guess What’s in Steve Wozniak’s Backpack",
    "Content": "\"Sometimes TSA takes a long time unpacking it,\" Wozniak says. \"A couple of times they asked me to take out everything electronic and I asked for seven bins, all of which I filled (only 2 half-size), plus my MacBook Pro, plus the bag. All of that through the X-ray machine. Then repack it.\"",
    "DocumentDate": "2012-06-15T13:00:00",
    "Culture": "en-US"
}

Possible Responses: 202 (Accepted)

Possible Error Status Codes:

• CodeExplanation
• 412The request body must contain a HarisDocument
• 412Part Space can not be null or emptry or longer than 16 characters
• 412Url can not be null or empty
• 412Url can not be longer than 250 characters
• 412Url must be in absolute uri format e.g.; file://C:\\my-file.pdf, http://www.my-site.com/my-page.html
• 412Culture code must be in correct format e.g.; en, en-US, en-IE, tr, tr-TR
• 412Given document date is out of range: {documentDate}

4.3. UnIndex Document

With this request the API unindexes a document from the database.

Request (DELETE)

http://444.kimola.com/api/{key}/document?url={url}

- url : Url of the document to be unindexed

Possible Responses: 202 (Accepted)

Possible error status codes special for this operation:

• CodeExplanation
• 412Url can not be null or empty
• 412Url can not be longer than 250 characters
• 412Url must be in absolute uri format e.g.; file://C:\\my-file.pdf, http://www.my-site.com/my-page.html

4.4. Truncate Documents

This request deletes all the indexes within the given API key.

Resquest (DELETE)

http://444.kimola.com/api/{key}/documents

Possible Responses: 202 (Accepted)

4.5. Get Part Spaces

This request gives you all the partspaces that an API key hosts.

Request (GET)

http://444.kimola.com/api/{key}/partspaces

Possible Responses: 202 (Accepted)

4.6. Delete Part Space

This request deletes the given partspace from the given API key.

Request (DELETE)

http://444.kimola.com/api/{key}/partspaces/{name}

Possible Responses: 202 (Accepted)

Possible error status codes special for this operation:

• CodeExplanation
• 412Part Space can not be null or emptry or longer than 16 characters

4.7. Search

This requests searches API with the given term and partspace, orders results by criteria and creates pagination with pageIndex and pageLength.

Request (GET)

http://444.kimola.com/api/{key}/search?partspace=null&term=Cloud+Search&criteria=0&pageIndex=0&pageLength=5

- term : Search term can be a single or more than one word.
- partspace : Searches the given partspace only. Don't send this parameter if you want to search in all partspaces.
- criteria : Sort order criteria for the results. This field can be:
0 for Relational Descending
1 for Relational Ascending
2 for Chronological Descending
3 for Chronological Ascending
- pageIndex : Starting page index of the search result. This value cannot be less than zero (0)
- pageLength : Determines how many search results will be shown in a single page. This value cannot be less than one (1) or greater than twenty-five (25).

Response Format:

{
"Duration":0.0,
"ApproximateCount":2,
"Items":
   [
      {
         "Url":"http://www.myamazingblog.com/blog-post-15/",
         "Title":"An amazing Blog Post",
         "Content":"My blog content about new Cloud Search service of Kimola!",
         "ImageUrl":"http://www.myamazingblog.com/uploads/amazing-image.jpg",
         "Phrases": [ "Cloud Search", "Kimola" ],
         "DocumentDate":"2011-07-21T21:00:00"
      },
      {
         "Url":"http://www.myamazingblog.com/blog-post-18/",
         "Title":"Another amazing Blog Post",
         "Content":"Another blog content about how to use Cloud Search API!",
         "ImageUrl":"http://www.myamazingblog.com/uploads/another-image.jpg",
         "Phrases": [ "Cloud Search", "API" ],
         "DocumentDate":"2012-09-13T17:00:00"
      }
   ]
}

Possible error status codes special for this operation:

• CodeExplanation
• 412term can not be null or empty
• 412criteria must be between 0 and 3
• 412pageIndex cannot be less than 0
• 412pageLength must be between 1 and 25

4.8. Get Phrases

The API orders search suggestions by their frequency in the database. This also allows to show the terms that have high probability of being searched on the upper ranks.

Request (GET)

http://444.kimola.com/api/{key}/phrases?url={url}

Response Format: { “phrase-1”, “phrase -2” }

Possible error status codes special for this operation:

• CodeExplanation
• 412Url can not be null or empty
• 412Url can not be longer than 250 characters
• 412Url must be in absolute uri format e.g.; file://C:\\my-file.pdf, http://www.my-site.com/my-page.html

4.9. Get Suggestions

The API orders search suggestions by their frequency in the database. This also allows to show the terms that have high probability of being searched on the upper ranks.

Request (GET)

http://444.kimola.com/api/{key}/suggestions/{term}

Response Format: { “suggestion-1”, “suggestion -2” }