API for Orilango Predict

Welcome to the Orilango predict API. The API enables you to deliver clever predictions to user input from your own application or web site. The API is a simple JSON-based RESTful HTTP-API.

In short, you do a simple GET-request with the user input and get a JSON-object with suggestions in return.

Before you can start using the API, you need to ask us for an api-key.

Request format

The API communicates over RESTful HTTP. The request contains these parts:

base-url	The url to the Orilango predict service: https://api.orilango.com/v2/predict/
apikey	Your api-key
input	The input to get predictions on. For example, the contents of the search field on your web site. The input needs to be url-encoded

The api-key can be sent either as part of the url or in the header. If you make a call to Orilango Predict directly from the frontend (i.e with JavaScript) you can send the api-key as part of the url. If you make a call using a server-side language we recommend sending the key in the header.

Example when sending the api-key as part of the url

https://api.orilango.com/v2/predict/myapikey/sho

Example when sending the api-key in the header

We're using the curl command to illustrate the example

curl https://api.orilango.com/v2/predict/sho -H "Api-Key: myapikey"

Response format

The API returns JSON-encoded objects (content-type: application/json). The response contains these parts:

original	The original input that was sent in the request
result	An array of suggestions to the original input.

Result

Result is an array where each entry is a JSON-object containing the following parts:

id	The id of the suggestion. If you upload your own list of items to Orilango, this could be an article id.
title	The title of the suggestion.
keywords	The keywords of the suggestion. Predictions will be returned based on these keywords as well as the title.
additionalData	Additional data related to the suggestions. If you upload a list of store items, this could be any data you want to display in the predict-dropdown. For example image-url, price, etc.

Example

						{
							"original": "cho",
							"result": [
								{
									"id": "234",
									"title": "Chocolate bar",
									"keywords": [],
									"additionalData": "{"img":"bar.jpg", price:"32"}"
								},
								{
									"id": "3412",
									"title": "Dark chocolate",
									"keywords": ["chocolate", "premium chocolate"],
									"additionalData": "{"img":"darkchocolate.jpg", price:"85"}"
								},
								{
									"id": "2785",
									"title": "Mars",
									"keywords": ["chocolate bar"],
									"additionalData": "{"img":"mars.jpg", price:"43"}"
								}
							]
						}

Example code

Ok, cool enough. Now you want to start using this API. Here's some example code in HTML and Javascript using the jQuery UI autocomplete library

HTML

Create a small html-file including the necessary Javascript and CSS files. Add a textfield to the page and assign it an id.

					<!doctype html>
					<html lang="en">
					<head>
					  <meta charset="utf-8" />
					  <title>Orilango autocomplete example</title>
					  <link rel="stylesheet" href="https://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
					  <script src="https://code.jquery.com/jquery-1.9.1.js"></script>
					  <script src="https://code.jquery.com/ui/1.10.3/jquery-ui.js"></script>
					</head>
					<body>
					  <input id="mytextfield" />
					</body>
					</html>

Javascript

Add a small piece of javascript to the page using the jQuery UI Autocomplete library. Remember to replace {apikey} with your real key

					  $(function() {
						$( "#mytextfield" ).autocomplete({
					      source: function( request, response ) {
					        $.ajax({
					          url: "https://api.orilango.com/v2/predict/{apikey}/"+request.term, //Append the content of the text field to the request
					          dataType: "json",
					          success: function( data ) {
								//Pick the "title" property from all elements in the "result" array and store in a new array
					            var suggestions = data.result.map(function(s) {
									return s.title;
								});
								response(suggestions);
					          }
					        });
					      },
					      minLength: 2,
					    });
					  });

Complete example

This is the final complete code example

					<!doctype html>
					<html lang="en">
					<head>
					  <meta charset="utf-8" />
					  <title>Orilango autocomplete example</title>
					  <link rel="stylesheet" href="https://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" />
					  <script src="https://code.jquery.com/jquery-1.9.1.js"></script>
					  <script src="https://code.jquery.com/ui/1.10.3/jquery-ui.js"></script>
					  <script>
					  $(function() {
						$( "#mytextfield" ).autocomplete({
					      source: function( request, response ) {
					        $.ajax({
					          url: "https://api.orilango.com/v2/predict/{apikey}/"+request.term, //Append the content of the text field to the request
					          dataType: "json",
					          success: function( data ) {
					            //Pick the "title" property from all elements in the "result" array and store in a new array
					            var suggestions = data.result.map(function(s) {
									return s.title;
								});
								response(suggestions);
					          }
					        });
					      },
					      minLength: 2,
					    });
					  });
					  </script>
					</head>
					<body>
					  <input id="mytextfield" />
					</body>
					</html>

Orilango API