This section explains how to use the API methods. The further explanations and sample code pieces assume that the API connector is implemented as described in the API integration section and can be accessed as follows:
$api = new RecognizeImApi();
The SOAP API methods return responses in the form of a map object described in the table below. Please note that the "status" fiels is not an HTTP status, but a part of the response data being returned along with the "200 OK" HTTP status.
|status||Always.||Indicates request success or informs about a failure
(0 — success, 1 — failure).
|message||On failure.||Explains the details of the failure.|
|data||On success, only if required.||Provides the requested response data.|
The list of available SOAP API methods with descriptions is presented below:
Authenticates the User.
You can choose to maintain the SOAP session at your side to keep your SOAP API connector authenticated. Otherwise, you might need to take care of authentication before executing every SOAP request separately.
Please refer to your profile for your credentials.
$userId = 12345; $keySoap = 'a0b1c2d3e4f5g6h7i8j9k10l11m12n13'; $response = $api->auth($userId, $keySoap);
Inserts an image to the reference object collection.
The image has to be uploaded with a unique ID (255 chars), which will be later returned in your recognition results. The name parameter is not mandatory, and you can use it to store the path to the image, which might help you find it in your local storage in the future, or to define another metadata you might need for any reason. The image data will be used to represent a recognizable object associated with its ID. You can choose to upload Base64-encoded image data.
A newly added object is not recognizable right away. It requires some pre-processing before it is ready to be included into recognizable objects. Please refer to the image statuses for further details.
$id = 'my-unique-object-id'; $name = 'my-image-name.jpg'; $image = file_get_contents('./my-reference-images/'.$name); //$image = base64_encode($image); //Optionally. $response = $api->imageInsert($id, $name, $image);
$id = 'my-unique-object-id'; $response = $api->imageGet($id);
Updates the metadata of an image.
You can use it to alter the ID and the name of the image. Changes take place immediately and will be visible in the recognition results right away.
Please note that it cannot be used to alter the image data. To re-define a recognizable object, you have to delete the image and upload a new one.
$id = 'my-unique-object-id'; $data = array( 'id'=>'my-new-unique-object-id', 'name'=>'my-new-object-name', ); $response = $api->imageUpdate($id, $data);
Deletes an image or all the images.
Depending on the status of the image you are going to delete, changes might not take place immediately, and the object might still be recognizable. The image gets removed permanently if it was erroneous or invalid; otherwise, it only receives the status indicating that it is scheduled to be removed and remains in the recognizable object collection until its next changes application. Please refer to the image statuses for further details.
$id = 'my-unique-object-id'; $response = $api->imageDelete($id); //Deletes a single image. $response = $api->imageDelete(); //Deletes all the images. Use carefully.
Returns a list of the reference images.
Due to data transfer limitations, you are able to fetch the images in chunks of size up to 50 entries. If you wish to fetch more data, you can enclose this method within a loop and increment the offset, determining where the current chunk starts.
The age of the images orders the list — those recently added go before the ones added long ago.
$limit = 5; $offset = 20; $response = $api->imageList(array('limit'=>$limit, 'offset'=>$offset)); $response = $api->imageList(); //Defaults: limit = 50, offset = 0.
Applies the reference collection changes by building the index of recognizable objects.
Initializes an asynchronous process of indexing the recognizable objects, whose duration depends on objects' number in the reference collection. You can set the callback URL to be notified when the process is accomplished, or alternatively, you can check the indexStatus periodically to determine that the process has ended.
This method affects all the images present in the reference collection before it is called — it alters their statuses and clears out the ones scheduled to be removed. Please refer to the image statuses for details.
You can keep adding new images into the collection before the process is finished, but keep in mind that the current indexing process will ignore the images added after the process has been initialized.
Please note that the term of "changes applying" refers to a User-level action of confirming the changes made to the reference image collection, while "indexing" or "building the index of recognizable objects" describes a technical process of a search index creation that makes recognition fast and efficient. All you need to know is that we might exchange these terms in our documents, and you should consider them equivalent.
$response = $api->indexBuild();
Returns the index status, which indicates whether or not the recognition service is active and provides general information about the reference image collection.
The response contains the "status" field, which refers to the reference image collection status (not image status), or recognition service status. The "progress" field shows the changes applying process advancement expressed as a percentage. The "needUpdate" field represents the number of images whose status indicates that they require changes applying to be executed. The remaining fields correspond to the image statuses, and they return the counts of the reference images carrying particular statuses.
|The "status" field value||Meaning|
|ok||Recognition service active.|
|processing||Changes applying in progress, recognition service might stop temporarily.|
|stopped||Recognition service stopped, reference image collection empty.|
|error||Recognition service failure. Try to apply changes once again or contact us.|
Hint: Use this method after adding a batch of images to veirfy whether they all have been pre-processed (indicated by the image statuses) before calling the indexBuild method to ensure that all newly added images will be included in the recognizable object collection.
$response = $api->indexStatus();
Sets or resets a callback URL.
Your URL will be notified by the API using a POST request on changes applying "process accomplished" events.
$url = 'http[s]://my.callback.url'; $response = $api->callback($url); //Set. $response = $api->callback(); //Reset.
Returns the current recognition mode.
$response = $api->modeGet();
Sets a recognition mode.
$mode = 'single'; $response = $api->modeSet($mode);
Returns the available limits and the consumed portion of these limits.
In particular, it involves the reference collection capacity and the number of recognition actions (scans) available in your current subscription.
$response = $api->userLimits();
The REST API methods return responses in the form of a JSON string described in the table below. Please note that the "status" fiels is not an HTTP status but a part of the response data being returned along with the "200 OK" HTTP status.
|status||Always.||Indicates request success or informs about a failure
(0 — success, 1 — failure, 2 — no objects found).
|message||On failure or when no objects found.||Explains the details.|
|objects||On success, only if required.||Provides the requested response data.|
The only available REST API method is described below:
Performs a recognition request.
It compares a query image against the reference collection and returns the recognized objects in the form of a list ordered by the confidence level. A set of four points in the form of (x, y) coordinates is provided for each recognized object, allowing to determine its location in the query image or mark these objects with bounding boxes. You can determine the orientation of the recognized object using these coordinates, taking advantage of the fact that they are assigned to specific, always the same vertices of the corresponding reference image, in the following order: upper-left, upper-right, lower-right, lower-left.
$imagePath = './img/my-query-image.jpg'; $mode = 'single'; $response = $api->recognize(file_get_contents($imagePath), $mode);
Still have questions?