API integration


The API is divided into two separate parts — the REST API for handling the recognition requests, and the SOAP API for the reference collection and account management. This section describes how to construct the API connectors and use them to call API methods and provides some code examples.

You can also refer to our GitHub repositories for some ready-made sample codes and example applications to help you get started with your own solutions.


Your API connector will need to know the API URL and provide your credentials for authentication. It might be convenient to gather these parameters as a configuration of the API connector object:

class RecognizeImApi { protected $config = array( 'url' => '', 'user_id' => 12345, 'key_rest' => 'a0b1c2d3e4', 'key_soap' => 'a0b1c2d3e4f5g6h7i8j9k10l11m12n13', ); }


You can add a SOAP client instance to the API connector object to be able to handle the SOAP calls:

//WSDL mode: protected $soap = new SoapClient( $this->config['url'].'/wsdl', array( 'trace' => 1, 'cache_wsdl' => WSDL_CACHE_NONE, ) ); //Non-WSDL mode: protected $soap = new SoapClient( NULL, array( 'location' => $this->config['url'], 'uri' => $this->config['url'], 'trace' => 1, 'cache_wsdl' => WSDL_CACHE_NONE, ) );

Finally, you have to ensure that your SOAP requests will be authenticated. You can call the auth method before every other SOAP method call or in the API connector object's construction or initialization. In the second case, keep in mind that the SOAP session will expire over time, and you will need to re-authenticate.

try { $response = $this->soap->auth($this->config['user_id'], $this->config['key_soap']); if ($response['status'] != 0) { $this->soap = NULL; echo "Error: ".$response['message']."\n"; } } catch (SoapFault $e) { $this->soap = NULL; echo "SOAP error: ".$e->getMessage()."\n"; }

Now that you have a valid SOAP client instance in your API connector, you can use it to call the SOAP API methods:

// 1. Using a SOAP connector getter. //In your API connector: public function &getSoap() { return $this->soap; } //Outside: $api = new RecognizeImApi(); $response = $api->getSoap()->methodName([param1[, param2[ , ...]]]); // 2. Using the magic '__call' method. //In your API connector: public function __call($name, $arguments) { if (!is_null($this->soap)) { response = call_user_func_array(array($this->soap, $name), $arguments); //This might be a good place to detect an expired SOAP session and re-authenticate. return $response; } else { echo "Invalid SOAP connector.\n"; return NULL; } } //Outside: $api = new RecognizeImApi(); $response = $api->methodName([param1[, param2[ , ...]]]);


The REST calls can be implemented using cURL. The current API version (v2) uses the REST protocol to handle the recognize method only. You can implement the recognize method wrapper in your API connector object:

public function recognize($image, $mode = 'single') { // $image = base64_encode($image); //Optionally. $hash = md5($this->config['key_rest'].$image); $url = $this->config['url'].'/v2/recognize/'.$mode.'/all/'.$this->config['user_id']; $response = NULL; try { $ch = curl_init($url); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array('x-itraff-hash: '.$hash, 'Content-type: image/jpeg')); curl_setopt($ch, CURLOPT_POST, TRUE); curl_setopt($ch, CURLOPT_POSTFIELDS, $image); $response = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($status != 200) { throw new Exception('Request failed.'); } } catch (Exception $e) { return $e->getMessage(); } // return (array)json_decode($response); //Optionally: decoded JSON string. return $response; //JSON string. }

You can choose to send Base64-encoded data if that is more convenient for you. Note that every single request is secured by a hash made of your credentials and the image data. If you wish to send Base64-encoded data, please convert it before computing the hash.

Now you can call the recognize method using your API connector as follows:

$api = new RecognizeImApi(); $imagePath = './img/my-query-image.jpg'; $mode = 'single'; $response = $api->recognize(file_get_contents($imagePath), $mode);

Still have questions?
Contact us!

This website uses cookie files. Using this website without changing your browser's cookies settings means that the cookie files will be stored in the device's memory.