Differences

This shows you the differences between two versions of the page.

Link to this comparison view

engine:7.0:api [2014/04/10 16:54]
alamy [GetTaskStatus | **DEPRECATED**]
engine:7.0:api [2018/02/01 18:15]
Line 1: Line 1:
-===== Introduction,​ LTU engine API's ===== 
-The principal API's are used for 
-  ***Image Management** to add and delete images, referenced as the **MODIFY** API 
-  ***Image Search** to retrieve images, referenced as the **QUERY** API 
-\\  
-Special use API's are used for: 
-  *Status Information on Images (GetImageByID - exists in both MODIFY and QUERY) 
-  *Status Information on Applications (GetApplicationStatus - exists in both MODIFY and QUERY) 
- 
- 
-===== API's - Two Distinct Categories: ​ MODIFY & QUERY ===== 
-\\  
-All LTU engine queries fall into one of two general API categories: ​ MODIFY or QUERY. 
-\\  
-\\  
-:!: For **LTU engine/ON demand**, the url of the query examples given in the following pages should be modified as follows : 
-  ***MODIFY** ​ - https://​api.ltu-engine.com/​v2/​ltumodify/​json/​ 
-  ***QUERY** - https://​api.ltu-engine.com/​v2/​ltuquery/​json/​ 
-\\  
-For **LTU engine/​server** 
-  ***MODIFY** - addressed via port 7789 
-  ***QUERY** - addressed via port 8080 
-\\  ​ 
- 
-|< 100% 150px -  7.0px >| 
-^  API Category ​ ^  Port  ^                                 ​Example ​                                ^ 
-|   ​**Modify** ​  ​| ​ 7789  | [[http://​hostaddress:​7789/​api/​v2.0/​ltumodify/​json/​AddImage]] ​           | 
-|   ​**Query** ​   |  8080  | [[http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​SearchImageByUpload]] ​ | 
- 
- 
- 
-\\  
-Some LTU engine API queries exist in **two versions** (MODIFY & QUERY), discussed above under "​Special USE API'​s"​. 
- 
-The LTU engine API is accessible over the HTTP protocol. 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-LTU engine requires a ''​GET''​ or a ''​POST''​ request as input, and returns an HTTP response with the application/​json mimetype, which contains the response serialized as a JSON string. 
- 
-<sxh jscript; title: SearchImageById Example:>​ 
-GET http://​localhost:​8080/​api/​v2.0/​ltuquery/​json/​SearchImageById?​application_key=j6hcA7bwb1jcF8grn6msWNoziUSbXWab&​image_id=myimage.jpg 
-</​sxh>​ 
-\\  
-**JSON response** 
-<sxh jscript; title: Example response:>​ 
- 
-  { 
- "​images":​[ 
-    { 
-     "​keywords":​["​office"​],​ 
-     "​score":​0,​ 
-     "​id":"​TO-018.jpg",​ 
-     "​result_info":"​{"​category":​ "​LOCALMATCHING",​ ...}" 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​1 
-} 
-</​sxh>​ 
- 
-In this documentation,​ you will find a list of all API methods. 
- 
-Each section will : 
-  * quickly explain what the method does. 
-  * define what type of HTTP request is accepted (''​GET'',​ ''​POST''​ or both). 
-  * define each parameter the method takes as input, its type, valid values, and whether it is mandatory or optional. 
-  * give an example response, with comments. 
- 
-Some notions are common to most API methods : 
- 
-  * //​application_key//​ : it is a unique identifier for an application. It needs to be present in ALL your LTU engine requests. 
-  * //​image_id//​ : it is a unique identifier of an image inside an application. When adding an image, you provide an //​image_id//​. The results of searches in a LTU engine application will be the provided //​image_id//​s. 
- 
- 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-===== Principal API'​s: ​ Add & Delete Images ===== 
-The modify API is usually exposed on http://​localhost:​7789/​api/​v2.0/​ltumodify/​json 
-==== AddImage ==== 
-  * **Request type :** ''​POST''​ 
-  * **Required Parameters** : 
-    * application_key (string): the unique key of the application to query. 
-    * image_id (string): The unique identifier of the image. 
-    * image_content (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Optional Parameters**:​ 
-    * dna (string): a byte array representing the precomputed DNA for the image. ​ 
-    * keywords (list of strings): one or more keywords that will be associated to this image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    ​ 
-Note that you can only specify one of //​image_content//​ or //dna//. 
- 
- 
-Simple example, curl, adding an image with '​pinpin'​ as //​image_id//​ and two keywords "​a"​ and "​b":​ 
- 
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL -F "​image_content=@pinpin.jpg" ​ 
-'​http://​hostaddress:​7789/​api/​v2.0/​ltumodify/​json/​AddImage?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin&​keywords=a&​keywords=b'​ 
-</​sxh>​ 
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
- "​status":​ 
-  { 
-   "​message":"​Image added to the reference database",​ 
-   "​code":​0 
-  }, 
- "​task_id":​0 
-} 
-</​sxh>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-==== DeleteImage ==== 
-Remove an image from you reference database. 
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters** : 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​7789/​api/​v2.0/​ltumodify/​json/​DeleteImage?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin'​ 
-</​sxh>​ 
- 
-\\  
-**JSON response** 
-\\  
-<sxh jscript; title: Sample result>{ 
- "​status":​ 
-  { 
-   "​message":"​Image deleted from the reference database",​ 
-   "​code":​0 
-  }, 
- "​task_id":​0 
-} 
-</​sxh>​ 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
- 
-===== Principal API'​s: ​ Search Images ===== 
- 
-The modify API is usually exposed on http://​localhost:​7789/​api/​v2.0/​ltuquery/​json 
- 
-There are four methods to run search queries :  
-  *SearchImageByUpload : search your reference database by sending an image file 
-  *SearchImageByDna:​ search your reference database by sending a precomputed DNA 
-  *SearchImageById:​ search your reference database by using the image with the given //​image_id//​. Not available for Mobile Matching applications. ​ 
-  *SearchImageByKeywords:​ search your reference database for image with this combination of keywords 
- 
-\\  
-All of these search methods have parameters in common. They are described here : 
-\\  
- 
-**Common Parameters** 
-\\ 
-^    Parameter ​    ​^ ​                                                                                                                          ​Description ​                                                                                                                           ^ 
-|     ​keywords ​    | Restrict the search to a list of keywords. Images that do not have these keywords will be discarded in the search. It is a list of strings and defaults to an empty list thus not restricting the search. ​                                                                                                                                        | 
-|   ​color_weight ​  | Only applicable for //Image Similarity//​ application. //​color_weight//​ defines the importance of color when doing a //​SearchImageByDna//​ or //​SearchImageByUpload//​. Defaults to 50 (balance between color and shape), values are integers in the range [0, 100]  | 
-|    nb_results ​   | Return at most //​nb_results//​ images no matter how many images actually matched the query image. Max value is 1,000 , defaults to 10                                                                                                                             | 
-|  starting_index ​ | LTU's algorithms being deterministic they will always return images that matched a given query in the same order. //​starting_index//​ allows to get results starting at a specific index. Defaults to 0.                                                          | 
-|     ​ids_list ​    | Restrict the search to the //​image_id//​s in this list. It is a string of coma separated //​image_id//​s. Maximum size is 10,​000. ​                                                                                                                                                                                    | 
- 
- 
-==== Result info ====  
- 
-Query results contain additional information in a "​result info" structure. ​ 
-  ***__Media monitoring__** 
-<sxh jscript> 
-{ 
-  "​category"​ : "​LOCALMATCHING",​ 
-  "​query"​ : 
-  { 
-    "​resizedDimensions"​ : [202, 324], 
-    "​matchingBox"​ : 
-    { 
-      "​topLeftPoint"​ : [0.3119, 0.7500], 
-      "​bottomRightPoint"​ : [0.5990, 0.8580] 
-    } 
-  }, 
-  "​reference"​ : 
-  { 
-    "​resizedDimensions"​ : [210, 312], 
-    "​matchingBox"​ : 
-    { 
-        "​topLeftPoint"​ : [0.2714, 0.7628], 
-        "​bottomRightPoint"​ : [0.5762, 0.8910] 
-    } 
-  }, 
-  "​distance"​ : 0.8615, 
-  "​homography"​ : 
-  { 
-    "​source"​ : "​reference",​ 
-    "​destination"​ : "​query",​ 
-    "​coefficients"​ : [1.0371, 0.2986, -0.1197, -0.2293, 1.4260, -0.0786, -0.2856, 0.4483, 1.0000] 
-  }, 
-  "​decision"​ : "​Match"​ 
-} 
-</​sxh>​ 
- 
-   ​*__category:​__ "​LOCALMATCHING"​ (constant) 
-   ​*__query:​__ information about the query 
-    *__resizedDimensions:​__ size of the processed image after resizing 
-    *__matchingBox:​__ the matching box is always rectangular with no rotation 
-      *__topLeftPoint:​__ coordinates of the top left point of the matching box 
-      *__bottomRightPoint:​__ coordinates of the top left point of the matching box 
-   ​*__reference:​__ information about the reference (see query) 
-   ​*__distance:​__ matching score, best matches have a low distance 
-   ​*__homography:​__ transformation from the reference to the query 
-   ​*__decision:​__ String describing the decision, possible values are 
-    *//"​Clone"//​ if the query is the same image as the reference 
-    *//"​Match"//​ 
-    *//"​Similar"//​ if the query does not match but is similar 
-    *//"​Different"//​ if the query does not match at all 
- 
-  ***__Mobile matching & Brand monitoring__** 
-<sxh jscript> 
-{ 
-  "​category"​ : "​LOCALMATCHING",​ 
-  "​query"​ : 
-  { 
-    "​originalDimensions"​ : [472, 755], 
-    "​resizedDimensions"​ : [640, 1024], 
-    "​matchingBox"​ : 
-    { 
-      "​points"​ : [ [0.2417, 0.3734], [0.8262, 0.3389], [0.7659, 0.8569], [0.2568, 0.8544]], 
-      "​area"​ : 0.2728 
-    } 
-  }, 
-  "​reference"​ : 
-  { 
-    "​originalDimensions"​ : [520, 770], 
-    "​resizedDimensions"​ : [345, 512], 
-    "​matchingBox"​ : 
-    { 
-      "​points"​ : [ [0.2029, 0.3691], [0.7565, 0.3691], [0.7565, 0.8887], [0.2029, 0.8887]], 
-      "​area"​ : 0.2876 
-    } 
-  }, 
-  "​distance"​ : 0.9046, 
-  "​scores"​ : 
-  { 
-    "​boxCoveredSurface"​ : 0.2500, 
-    "​boxPointsRatio"​ : 0.1409, 
-    "​boxPointsRatioHomography"​ : 0.7255, 
-    "​matchStrength"​ : 0.0954 
-  }, 
-  "​homography"​ : 
-  { 
-    "​source"​ : "​reference",​ 
-    "​destination"​ : "​query",​ 
-    "​coefficients"​ : [1.0227, 0.1058, 0.0141, -0.1149, 1.2461, -0.0339, -0.1404, 0.2897, 1.0000] 
-  }, 
-  "​decision"​ : "​Match"​ 
-} 
-</​sxh>​ 
- 
-   ​*__category:​__ "​LOCALMATCHING"​ (constant) 
-   ​*__query:​__ information about the query 
-    *__originalDimensions:​__ size of the original image 
-    *__resizedDimensions:​__ size of the processed image after resizing 
-    *__matchingBox__ 
-      *__points:​__ vertices of the matching box inside the query 
-      *__area:__ surface of the matching box in percentage (0.2728 -> 27.28 %) 
-   ​*__reference:​__ information about the reference (see query) 
-    *__matchingBox:​__ for the reference, the matching box is always rectangular with no rotation 
-   ​*__distance:​__ matching score, best matches have a low distance 
-   ​*__scores:​__ alternative scores 
-    *__boxCoveredSurface:​__ surface within the matching box with matching points (expressed as percentage) 
-    *__boxPointsRatio:​__ do not use this score as it is incompatible with this signature 
-    *__boxPointsRatioHomography:​__ ratio of matching points among all points in the query matching box 
-    *__matchStrength:​__ normalized score based on the number of matching points 
-   ​*__homography:​__ transformation from the reference to the query 
-   ​*__decision:​__ String describing the decision, possible values are 
-    *//"​Clone"//​ if the query is the same image as the reference 
-    *//"​Match"//​ 
-    *//"​Rejection due to geometric test"//​ 
-    *//"​Rejection due to shape of the matching box"// 
- 
- 
-  ***__Similarity__** 
-<sxh jscript> 
-{ 
-  "​category"​ : "​SIMILARITY",​ 
-  "​colorScore"​ : 0.4011, 
-  "​shapeScore"​ : 0.8148, 
-  "​colorweight"​ : 0.5000 
-} 
-</​sxh>​ 
- 
-   ​*__category:​__ "​SIMILARITY"​ (constant) 
-   ​*__colorScore:​__ score solely based on the colors 
-   ​*__shapeScore:​__ score solely based on the shapes 
-   ​*__colorweight:​__ ratio between 0 and 1 to balance the weight of the color for the overall score 
-<​code>​ 
-score = (1 - colorweight) * shapeScore + colorweight * colorScore 
-</​code>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-**Note**: in the interest of brevity the //​result_info//​ is shown as empty in all the following sections. 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-==== SearchImageByUpload ==== 
-Runs an image search on an application,​ using an uploaded image as the query. 
-\\ 
-  * **Request type :** : ''​POST''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_content (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Optional Parameters :** 
-    * keywords (list of strings): one or more keywords that will be associated to this image. 
-    * color_weight (integer): how important is color in the search - only for //​Similarity//​ applications 
-    * starting_index (integer): index of the first image to be returned in the list of results 
-    * nb_results (integer): number of results to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-\\ 
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL -F "​image_content=@pinpin.jpg" ​ 
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​SearchImageByUpload?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'​ 
-</​sxh>​ 
- 
-\\  
-\\  
-**JSON response** 
- 
-<sxh jscript; title: Sample result> 
-{ 
-  "​images":​[ 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0,​ 
-     "​id":"​some_image.jpg",​ 
-     "​result_info":""​ 
-    }, 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0.719954,​ 
-     "​id":"​some_other_image.jpg",​ 
-     "​result_info":""​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​100 
-} 
-</​sxh>​ 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-==== SearchImageById ==== 
-Runs an image search on an application,​ taking an image from the database as the query. 
-\\ 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Optional Parameters :** 
-    * color_weight (integer): how important is color in the search - only for //​Similarity//​ applications 
-    * starting_index (integer): index of the first image to be returned in the list of results 
-    * nb_results (integer): number of results to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
- 
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​SearchImageById?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin'​ 
-</​sxh>​ 
- 
- 
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
-  "​images":​[ 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0,​ 
-     "​id":"​some_image.jpg",​ 
-     "​result_info":""​ 
-    }, 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0.719954,​ 
-     "​id":"​some_other_image.jpg",​ 
-     "​result_info":""​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​100 
-} 
-</​sxh>​ 
- 
-**Note that SearchImageById is not available for Mobile Matching applications. You will receive -2609 error code instead.** 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-==== SearchImageByDna ==== 
-The equivalent of a SearchImageByUpload,​ but where the DNA is precomputed on the client side, and send directly instead the image. 
-\\ 
- 
-  * **Request type :​**''​POST'' ​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * dna (string): a byte array representing the precomputed DNA for the image. 
-  * **Optional Parameters :** 
-    * keywords (list of strings): one or more keywords that will be associated to this image. 
-    * color_weight (integer): how important is color in the search - only for //​Similarity//​ applications 
-    * starting_index (integer): index of the first image to be returned in the list of results 
-    * nb_results (integer): number of results to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-  
-\\  
-**For information concerning pre-computed DNA's, please contact LTU support.** 
-\\  
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
-  "​images":​[ 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0,​ 
-     "​id":"​some_image.jpg",​ 
-     "​result_info":""​ 
-    }, 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0.719954,​ 
-     "​id":"​some_other_image.jpg",​ 
-     "​result_info":""​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​100 
-} 
-</​sxh>​ 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-==== SearchImageByKeywords ==== 
-Returns images that contain all keywords in a list. 
- 
-  * **Request type :​**''​POST''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * keywords (list of strings): one or more keywords that will be associated to this image. 
-  * **Optional Parameters :** 
-    * starting_index (integer): index of the first image to be returned in the list of results 
-    * nb_results (integer): number of results to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-    ​ 
-\\  
-Simple example, curl, keywords (a,b): 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​SearchImageByKeywords?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​keywords=a&​keywords=b'​ 
-</​sxh>​ 
-\\  
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
-  "​images":​[ 
-    { 
-     "​keywords":​['​a',​ '​b'​],​ 
-     "​score":​0,​ 
-     "​id":"​some_image.jpg",​ 
-     "​result_info":""​ 
-    }, 
-    { 
-     "​keywords":​['​a',​ '​b'​],​ 
-     "​score":​0.719954,​ 
-     "​id":"​some_other_image.jpg",​ 
-     "​result_info":""​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​100 
-} 
-</​sxh>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-===== Color Search API's ===== 
-The following section only applies to //Color// applications. 
- 
-When returning colors LTU engine use the following notation <​hex_color>​@<​percentage>:​ 
-  * //​hex_color//​ is the hexadecimal form of the color 
-  * //​percentage//​ is the proportion of the image the color is filling 
- 
-==== GetImageColorsById ==== 
-Returns the dominant colors and their percentage present in the image with the given //​image_id//​. 
- 
-\\  
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Response**:​ 
-    * status (object): ​ 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * colors (list of strings): the most prevalent colors in the image as <​hex_color>​@<​percentage>​ 
-  ​ 
-\\ 
-Simple example, curl: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​GetImageColorsById?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin'​ 
-</​sxh>​ 
-\\  
-**JSON response** 
- 
-<sxh jscript; title: Sample result> 
-{ 
- "​status":​ 
-  { 
-   "​message":"",​ 
-   "​code":​0 
-  }, 
- "​colors":​["​F2F2F2@94","​A9B5B6@2","​EAA453@1","​D5C0A3@1","​2B9755@1","​A0C99A@1"​] 
-} 
-</​sxh>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-==== GetImageColorsByUpload ==== 
-Returns the dominant colors and their percentage present in the uploaded image. 
-\\  
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_content (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Response**:​ 
-    * status (object): ​ 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * colors (list of strings): the most prevalent colors in the image as <​hex_color>​@<​percentage>​ 
- 
-\\ 
- 
-Simple example, curl: 
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL -F "​image_content=@pinpin.jpg" ​ 
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​GetImageColorsByUpload?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'​ 
-</​sxh>​ 
- 
-\\  
- 
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
- "​status":​ 
-  { 
-   "​message":"",​ 
-   "​code":​0 
-  }, 
- "​colors":​["​B9A595@24","​71715A@20","​E1DFDB@12","​494938@10","​1E1B12@7","​946C57@5","​030203@5","​0A0915@3","​866939@3","​0B0B07@2","​5B3E26@2","​3C2909@2","​CAB978@1","​B79439@1","​382911@1","​150E14@1","​6E6076@1"​] 
-} 
-</​sxh>​ 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-==== SearchImageByColors ==== 
-Search for images containing the given set of colors. 
-\\  
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * colors (list of strings): the colors you are looking for as <​hex_color>​@<​percentage> ​ 
-  * **Optional Parameters :** 
-    * keywords (list of strings): one or more keywords associated to the image 
-    * starting_index (integer): index of the first image to be returned in the list of results 
-    * nb_results (integer): number of results to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-  ​ 
-\\  
- 
-Simple example, curl: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​SearcImageByColors?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​colors=FF6633&​colors=FF99'​ 
-</​sxh>​ 
- 
- 
-**JSON response:** 
-<sxh jscript; title: Sample result> 
-{ 
- "​images":​[ 
-    { 
-     "​keywords":​["​Seurat"​],​ 
-     "​score":​0.741319597,​ 
-     "​id":"​Sunday_Afternoon_Island_G...",​ 
-     "​result_info":""​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​1 
-} 
-</​sxh>​ 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
-==== GetPalette ==== 
-Compute the most prevalant colors in an image set, by default all images in the application. 
- 
-Method: GET 
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-  * **Optional Parameters :** 
-    * keywords (list of strings): one or more keywords associated to the image 
-    * nb_colors (integer): the max number of colors to return 
-    * ids_list (string): list of //​image_id//​s among which to search 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * colors (list of strings): the most prevalent colors in the image as <​hex_color>​@<​percentage>​ 
-    * image_count (list of integers): number of image contain this color 
- 
-**Note**: a single index should be used to read the lists //colors// and //​image_count//​ since '​image_count[index]'​ is the number of images that contain the color '​color[index]'​. 
- 
-Simple example, curl: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​GetPalette?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​colors=FF6633&​colors=FF99'​ 
-</​sxh>​ 
- 
-\\  
-<sxh jscript; title: Sample result> 
-{ 
- "​status":​ 
-  { 
-   "​message":"",​ 
-   "​code":​0 
-  }, 
- "​colors":​["​735238","​8F938E","​2D5E95","​382711","​393126","​846834","​C3973A","​CFB076","​E9EAEB","​943112","​AA834F","​D91E25","​090A05","​0A0E30","​B15A4A"​],​ 
- "​image_count":​[5,​4,​3,​3,​3,​3,​3,​3,​3,​2,​2,​2,​1,​1,​1] 
-} 
-</​sxh>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
-===== Special Use API's ===== 
- 
-==== Image Fine Comparison ==== 
-  
-\\  
-Fine comparison is designed to provide additional details on the results of query and reference matches using LTU’s image matching functionality. ​ The fine image comparison feature provides visual feedback about matched images, pinpointing where the subtlest differences are located. 
-\\  
-\\  
-Fine comparison also provides a numeric score to quantify the differences between the two images. 
-\\  
-\\ 
-Fine comparison is used to: 
-Automate the identification of differences between two matching images and visually highlight the differences between these images. 
-\\  
-http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​FineComparison 
-\\  
-\\  
-  * **Request type :** ''​POST''  ​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * ref_image (string): the content of the image file i.e. the raw array of bytes in the image. 
-    * query_image (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Response :** 
-    * status (object): ​ 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * score (float): defines how close the image are, a higher score means more difference between the images 
-    * ref_image (b64 encoded string): raw jpg image, it is the same as the //​ref_image//​ sent but with highlighted differences with the //​query_image//​. 
-    * query_image (b64 encoded string): raw jpg image, it is the same as the //​query_image//​ sent but with highlighted differences with the //​ref_image//​. 
- 
- 
-\\ 
-Notes: 
-  * This feature is only available for //Media Matching// applications 
-  * It is best to call this method with that already matched since the purpose is to find smaller differences. 
-  * The reference image and the query image returned by the API are base64 encoded. 
- 
-\\  
-Simple curl example: 
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -F "​reference_image=@fic1.jpg"​ -F "​query_image=@fic2.jpg"​ "​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​FineComparison?​application_key=VmLGHUj9yXA731RD0Hzp9svWCb5MtMY1" ​ 
-</​sxh>​ 
- 
- 
-JSON response: 
-<sxh jscript; title: Sample result> 
-{ 
-  "​ref_image":​ "base 64 encoded diff on the reference image",​ 
-  "​query_image":​ "base 64 encoded diff on the query image",​ 
-  "​score":​ 1.2381811141967773,​ 
-  "​status":​ { 
-    "​message":​ "",​ 
-    "​code":​ 0 
-  } 
-} 
-</​sxh>​ 
- 
- 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
- 
- 
-==== GetApplicationStatus - QUERY version ==== 
-Returns information on the status of an application (how many images are loaded, etc.) 
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameter: ** 
-    * application_key (string): the unique key of the application to query 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_loaded_images(integer):​ number of images in the references database 
-\\  
-Simple curl example: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​GetApplicationStatus?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'​ 
-</​sxh>​ 
- 
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
-  "​status":​ { 
-    "​message":​ "No error",​ 
-    "​code":​ 0 
-  }, 
-  "​nb_loaded_images":​ 227 
-} 
-</​sxh>​ 
-==== GetApplicationStatus - MODIFY version ==== 
-Returns the status of an application (wether it is correctly loaded and fully operational,​ etc.) 
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-  * **Response :** 
-    * status (object): ​ 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * application_db_status (string): indicated whether the reference image database is accessible or not 
-    * main_db_status (string): indicated whether the database is accessible or not 
-    ​ 
-  ​ 
-\\  
-Simple curl example: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​7789/​api/​v2.0/​ltumodify/​GetApplicationStatus?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'​ 
-</​sxh>​ 
- 
-\\  
-\\  
-**JSON response** 
- 
-<sxh jscript; title: Sample result> 
-{ 
-  "​status":​ { 
-    "​message":​ "No error",​ 
-    "​code":​ 0 
-  }, 
-  "​application_db_status":​ "​available",​ 
-  "​main_db_status":​ "​available"​ 
-} 
-</​sxh>​ 
- 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
- 
-==== GetImageById - QUERY version ==== 
-Returns the image that has the given unique id.  
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * image (object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-  ​ 
- 
-Simple example, curl: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​7789/​api/​v2.0/​ltumodify/​json/​GetImageById?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin'​ 
-</​sxh>​ 
- 
-\\  
-**JSON response** 
- 
-<sxh jscript; title: Sample result> 
-{ 
-  "​status":​ { 
-    "​message":​ "No error",​ 
-    "​code":​ 0 
-  }, 
-  "​image":​ { 
-    "​keywords":​ ["​keyword"​],​ 
-    "​score":​ 0, 
-    "​id":​ "​COSMOS00145488_000001.jpg",​ 
-    "​result_info":​ ""​ 
-  } 
-} 
-</​sxh>​ 
- 
-==== GetImageById - MODIFY version ==== 
-Returns the image that has the given unique id.  
- 
-  * **Request type :​**''​GET''​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * image (object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
-      *  
-Simple example, curl: 
-\\  
-**CURL query** 
-<sxh php; title: Sample query> 
-curl -sL  
-'​http://​hostaddress:​8080/​api/​v2.0/​ltuquery/​json/​GetImageById?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=pinpin'​ 
-</​sxh>​ 
- 
-\\  
-**JSON response** 
-<sxh jscript; title: Sample result> 
-{ 
-  "​status":​ { 
-    "​message":​ "No error",​ 
-    "​code":​ 0 
-  }, 
-  "​image":​ { 
-    "​keywords":​ [ 
-      "​some_keyword"​ 
-    ], 
-    "​score":​ 0, 
-    "​id":​ "​da97e15e6b2faa06b1cd3708bf52ee1e.jpg",​ 
-    "​result_info":​ ""​ 
-  } 
-} 
-</​sxh>​ 
- 
-<​html>​ 
-<​pagebreak>​ 
-</​html>​ 
- 
- 
- 
-