This version (2013/08/02 13:18) is a draft.
Approvals: 0/1

Introduction: SOAP API [DEPRECATED, please use JSON API.]

In the document below, sample programs are provided in various programming languages, each demonstrating how to make calls to LTU engine/ON demand. When ready to integrate with LTU Engine/On demand, it is recommended to use this code as a starting point. However, please remember that this is not production code. There are many SOAP libraries available for most programming language, JASTEC does not directly support each library and strongly recommends using those provided in the samples. JASTEC will maintain the SOAP definition files -WSDL file -and assures their validity.

Web Service: Modify

This web service provides tools to manage the database of images. Two main functions are provided to add and delete images (AddImage and DeleteImage). They are gathered in a section of the API called “Modify”. All calls enter a work queue and are processed as soon as possible. In asynchronous mode every AddImage and DeleteImage call generates a task id that can be followed up via the GetTaskStatus function to monitor the process. This approach ensures high performance during large batches of addition and deletion calls.

IP address: Modify API

Version 2: https://api.ltu-engine.com/v2/ltumodify/soap

Version 1: https://api.ltu-engine.com/v1/ltumodify/soap

Version 1 old address is still active : https://modify.ltu-engine.com:443/post/

WSDL location

The WSDL file can be found in the LTU engine/ON demand SDK package.

Example application: Modify

SYNOPSIS
LTUengineONdemand_ModifySample.pl -a ACTION -k APPLICATION_KEY [options]

OPTIONS
-h, -help : Print a brief help message and exits.
-man: Prints the manual page and exits.
-a ACTION : Action to perform:

  • AddImage
  • DeleteImage
  • GetTaskStatus
  • GetApplicationStatus

-k : APPLICATION_KEY

AddImage

Purpose: Use this function to add new images to an application. Image_id can be used as a link between your existing image database and the LTU engine/ON demand database. Please note that image_id’s must be unique.

Options:

Must provide at least an image or a DNA or both.

-i IMAGE_ID [required] Image id

-f IMAGE_FILE Image file location

-d DNA_FILE DNA file location

-K KEYWORDS [optional] Keywords separated by ','

WSDL Excerpt

element name=“application_key” type=“xs:string”

element name=“image_id” type=“xs:string” element name=“image_format” type=“xs:string” />* element name=“image_content” type=“xs:base64Binary” element name=“dna” type=“xs:base64Binary” element name=“keywords” type=“tns:stringArray”

for version 1 only.

Sample Request: Add Image

LTUengineONdemand_ModifySample.pl -a AddImage -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -f ./myimages/image1.jpg -i image1

Typical Response

Run query 'AddImage' SOAP client created Add image 'image1' with keywords ' Action in queue with task_id '37': image added to the queue for async processing or directly with sync processing

Delete Image

Purpose: Use this function to remove an image from an application.

Options:

-i IMAGE_ID [required] Image id

WSDL Excerpt

element name=“application_key” type=“xs:string” element name=“image_id” type=“xs:string”

Sample Request
./LTUengineONdemand_ModifySample.pl -a DeleteImage -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -i image2

Typical Response
SOAP client created Delete image 'image2' Action in queue with task_id '214': Job added to the queue for async processing or deleted with sync processing

GetTaskStatus

Purpose: Use this function to check the status of specific requests (AddImage, DeleteImage)

Task Status Messages

“>0” : Task in progress
“<0” : Error
“0” : Task processed

Option:

-t TASK_ID [required] Task id

WSDL Excerpt

element name=“application_key” type=“xs:string” element name=“task_id” type=“xs:int”

Sample Request
./LTUengineONdemand_ModifySample.pl -a GetTaskStatus -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -t 10889

Typical Response
Run query 'GetTaskStatus' SOAP client created Get status on task '10889' Get task status -task_id='10889' task_status='process_error' task_status_code='2502' task_status_message='Can't add image to the application (an image with the same id already exist)'

GetApplicationStatus

Purpose: Use this function to verify that your application is available. Using the GetApplicationStatus query enables to check whether the service is running, that the application exists and to check the access rights for the current IP address and application key.

Options:

No options

WSDL Excerpt

element name=“application_key” type=“xs:string”

Sample Request
./LTUengineONdemand_ModifySample.pl -a GetApplicationStatus -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6

Typical Response
Run query 'GetApplicationStatus’ SOAP client created Get application status Get application status – UP status: No error

Web Service: Query

Query Web Service provides the ability to perform read-only queries on an application. Searching the existing numerous facets of each image entity.

IP address: Query API

Version 2: https://api.ltu-engine.com/v2/ltuquery/soap
Version 1: https://api.ltu-engine.com/v1/ltuquery/soap
Version 1 old address is still active: https://query.ltu-engine.com:443/search/
WSDL Location
The WSDL file can be found in the LTU engine/ON demand SDK package.

Example application: Query

SYNOPSIS LTUengineONdemand_QuerySample.pl -a ACTION -k APPLICATION_KEY [options]

OPTIONS
-h, -help : Print a brief help message and exits.
-man : Prints the manual page and exits.
-a ACTION: Action to perform

  • GetImageById
  • SearchImageById
  • SearchImageByUpload
  • SearchImageByDna
  • SearchImageByKeywords
  • GetApplicationStatus


-k APPLICATION_KEY Application key

GetApplicationStatus

Purpose: Use this function to confirm that an application’s search functionality is ready for use. If it is available, you can proceed with any search function call. This function only confirms ability to perform the search functions.

Using the GetApplicationStatus query enables to:

  • Check if the Service is running
  • Check the access rights for the current IP and application key
  • Check that this application exists


WSDL Excerpt
element name=“application_key” type=“xs:string”

Sample Request
./LTUengineONdemand_QuerySample.pl -a GetApplicationStatus -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6

Typical Response
Run query 'GetApplicationStatus' SOAP client created Get application status -UP status: No error, nb images loaded: 1

GetImageById

Purpose: This function searches the database for an image with a given image_id. This is a text based search on the image id. This function is typically used to deduplicate a database or check the existence of a reference.

Options: -i IMAGE_ID [required] Image id

WSDL Excerpt
element name=“application_key” type=“xs:string” element name=“image_id” type=“xs:string”
Sample Request
./LTUengineONdemand_QuerySample.pl -a GetImageById -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -i image1
Typical Response
Run query GetImageById' SOAP client created Get image by id 'image1' Get image by id -status: No error ltuImage id='image1' keywords='keyword1,keyword2' result info=’’*

*: not present in version 1.

SearchImageByUpload

Purpose: Use this function to query the application to compare an external image to the database and return a score with the distance between the queried images. Either use the image_file or calculate the DNA first and send it as the query. The latter option will result in faster network and computing time.

Options :
-i IMAGE_ID [required] : Image id

-K KEYWORDS [optional] : Keywords separated by ,
-c COLOR_WEIGHT [optional – only for similarity signatures] Weight of color in image comparison. Default is 50
-S STARTING_RANK [optional] Starting rank in results. Default is 0
-n NUMBER_OF_RESULTS [optional] : Number of results to retrieve. Default is 10
-l IDS_LIST [optional] : List of image ids separated by “;”. The search will be done in this set of images.

WSDL Excerpt
element name=“application_key” type=“xs:string” element name=“image_content” type=“xs:base64Binary” element name=“keywords” type=“tns:stringArray” element name=“color_weight” type=“xs:int” element name=“starting_index” type=“xs:int” element name=“nb_results” type=“xs:int” element name=“ids_list” type=“xs:string”

Sample Request
./LTUengineONdemand_QuerySample.pl -a SearchImageByUpload -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -f ./myimages/image1.jpg

Typical Response Run query 'SearchImageByUpload' SOAP client created Search image 'image1.jpg' with keywords Search Result -status: No error -number of results: 1 ltuImage id='image1' score='0.0' keywords= result info=’JSON_STRING’*

*: not available in version 1.

The result info string provides information on the matching zone – the areas of the images that matched. The string contains the coordinates to illustrate the matching zone on both the query image and the reference image along with the required geometric transformation that should be performed on the “source” image to obtain the “destination” image.

This attribute is a JSON formatted field embedded in a string. It is formatted as follow: 

{ 
"category" : "LOCALMATCHING", 
"query" : 
{ 

"resizedDimensions" : [queryWidth_in_%, queryHeight_in_%], 
"matchingBox" : 
{ 


"topLeftPoint" : [topLeftPoint_X, topLeftPoint_Y], 
"bottomRightPoint" : [bottomRightPoint_X, bottomRightPoint_Y] 


} 
}, 
"reference" : 
{ 


"resizedDimensions" : [referenceWidth_in_%, referenceHeight_in_%], 
"matchingBox" : 
{ 


"topLeftPoint" : [topLeftPoint_X, topLeftPoint_Y], 
"bottomRightPoint" : [bottomRightPoint_X, bottomRightPoint_Y] 


} 
}, 
"homography" : 
{ 


"source" : "reference", 
"destination" : "query", 
"coefficients" : [1.0000, 0.0000, 0.0000, 0.0000, 1.0000, 0.0000, 0.0000, 0.0000, 1.0000] 


} 
}

SearchImageById

Purpose: This function searches the database for an image with a given image_id. This is a text based search on the image id. This function is typically used to deduplicate a database or check the existence of a reference.

Options:
-i IMAGE_ID [required] : Image id
-K KEYWORDS [optional] : Keywords separated by ,
-c COLOR_WEIGHT [optional – only for similarity dna] : Weight of color in image comparison. Default is 50
-S STARTING_RANK [optional] : Starting rank in results. Default is 0
-n NUMBER_OF_RESULTS [optional] : Number of results to retrieve. Default is 10
-l IDS_LIST [optional] : List of image ids separated by “;”. The search will be done in this set of images.

WSDL Excerpt

element name=“application_key” type=“xs:string” element name=“image_id” type=“xs:string” element name=“keywords” type=“tns:stringArray” element name=“color_weight” type=“xs:int” element name=“starting_index” type=“xs:int” element name=“nb_results” type=“xs:int” element name=“ids_list” type=“xs:string”


Sample Request
./LTUengineONdemand_QuerySample.pl -a SearchImageById -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -i image1

Typical Response
Run query 'SearchImageById' SOAP client created Search image by id 'image1' with keywords Search Result -status: No error -number of results: 1 ltuImage id='image1' score='0.0' keywords= result info=’JSON_STRING’*

*: not present in version 1.

SearchImageByKeywords

Purpose: Use this function to search for images that are associated with one or more given keywords in a given application. This is a text based search. Multiple keywords will be combined with an AND operator. Meaning if searching for images that have the keywords ‘red,dog’ the search will look for ‘red’ AND ‘dog’ so if an image does not have both it will not be returned.

Options:
-K KEYWORDS [required] : Keywords separated by ,

-S STARTING_RANK [optional] : Starting rank in results. Default is 0
-n NUMBER_OF_RESULTS [optional] : Number of results to retrieve. Default is 10
-l IDS_LIST [optional] : List of image ids separated by “;”. The search will be done in this set of images.

WSDL Excerpt
element name=“application_key” type=“xs:string” element name=“keywords” type=“tns:stringArray” element name=“starting_index” type=“xs:int” element name=“nb_results” type=“xs:int” element name=“ids_list” type=“xs:string”

Sample Request
./LTUengineONdemand_QuerySample.pl -a SearchImageByKeywords -k I5g6cygQYRxnrfXaheSHXueRDUemCPp6 -K ltukeywordsample1, ltukeywordsample2, ltukeywordsample3
Typical Response
Run query 'SearchImageByKeywords' SOAP client created Search image by keywords 'ltukeywordsample1' Search Result -status: No error -number of results: 1 ltuImage id='image1' score='0.0' keywords=' ltukeywordsample1' result info=’’*

*: not present in version 1.

Error Codes

HTTP Error:

  • 403 Forbidden

This error occurs when an application key is wrong or does not match the IP address of the machine that is making the call.
To correct this error confirm that the current IP address is listed on the application’s IP address white list.

LTU engine/ON demand 4-digit error codes
There are 3 different types of errors that you need to be aware of. Each error code consists of 4 digits
the first digit indicates where the error comes from. For example, error codes ranging from 1000 to 2000 are client side errors.
Errore code format:

  • 1XXX Wrong or missing input parameter and thus the action can't be processed.
  • 2XXX Data integrity errors / wrong requests.
  • 3XXX Internal service error, please report it to JASTEC France