- Apimo Webservice 2.0 (apimo.com)
- PHP v5.5
This is an article on how I connected to the Apimo WebService. The Apimo Webservice is an API provided by apimo.com and requires a server request over HTTPS using the GET method.
Why?
This was quite difficult to connect to and to determine what was wrong with each step of the development as the error messages were somewhat vague. I thought I'd quickly write this article so I don't have to spend so much time on it again.
Note that the below examples, demonstrate a script on a Non-SSL-Enabled host.
How?
Previously, I would have used cURL but for some reason, I couldn't get the configuration right. After several days... I tried the example as per the Apimo documentation and it worked! There were a few adjustments to make which I'm documenting here.
Basic Example
Here's a complete PHP script of a basic example of getting the agencies belonging to a company (note you will need to change the keys and relevant IDs to match your own solution):
// specify provider ID $my_provider_id = 1234; $my_timestamp = time(); // specify company ID $company_id_1 = 1234; $company_id_2 = 4321; // specify agency ID $company_id_1_agency_id = ''; $company_id_1_brand_id = ''; // specify target url and version $apimo_url = 'https://api.apimo.com/api/call'; $apimo_version = 2; // specify data output $apimo_method = 'getAgencies'; $apimo_type = 'xml'; // specify key and encryption $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234'; // specify your assigned key here $apimo_sha = sha1($apimo_key.$my_timestamp); // receive content $output = file_get_contents( $apimo_url. '?provider='.$my_provider_id. '×tamp='.$my_timestamp. '&sha1='.$apimo_sha. '&method='.$apimo_method. '&type='.$apimo_type. '&version='.$apimo_version. '&agency='.$company_id_1_agency_id. '&company='.$company_id_1. '&brand='.$company_id_1_brand_id ); // remove XML declaration from results $output = substr($output, stripos($output, '?>') + 2 ); // remove leading spaces, carriage returns $output = trim($output); // process if type specified was xml if($apimo_type=='xml'){ // send header header("Content-Type:text/xml"); // print result to page echo $output; }
- // specify provider ID
- $my_provider_id = 1234;
- $my_timestamp = time();
- // specify company ID
- $company_id_1 = 1234;
- $company_id_2 = 4321;
- // specify agency ID
- $company_id_1_agency_id = '';
- $company_id_1_brand_id = '';
- // specify target url and version
- $apimo_url = 'https://api.apimo.com/api/call';
- $apimo_version = 2;
- // specify data output
- $apimo_method = 'getAgencies';
- $apimo_type = 'xml';
- // specify key and encryption
- $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234';  // specify your assigned key here
- $apimo_sha = sha1($apimo_key.$my_timestamp);
- // receive content
- $output = file_get_contents(
- $apimo_url.
- '?provider='.$my_provider_id.
- '×tamp='.$my_timestamp.
- '&sha1='.$apimo_sha.
- '&method='.$apimo_method.
- '&type='.$apimo_type.
- '&version='.$apimo_version.
- '&agency='.$company_id_1_agency_id.
- '&company='.$company_id_1.
- '&brand='.$company_id_1_brand_id
- );
- // remove XML declaration from results
- $output = substr($output, stripos($output, '?>') + 2 );
- // remove leading spaces, carriage returns
- $output = trim($output);
- // process if type specified was xml
- if($apimo_type=='xml'){
- // send header
- header("Content-Type:text/xml");
- // print result to page
- echo $output;
- }
Here's a complete PHP script of a more complex example of 1) getting the agencies belonging to a company then 2) getting the properties for each agency:
<?php // intialize a result count $property_count=0; // specify provider ID $my_provider_id = 1234; $my_timestamp = time(); // specify company IDs $target_company_ids = array(2345, 3456); // specify target url and version $apimo_url = 'https://api.apimo.com/api/call'; $apimo_version = 2; // specify data output $apimo_type = 'xml'; // specify key and encryption $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234'; $apimo_sha = sha1($apimo_key.$my_timestamp); // for($i=0;$i<count($target_company_ids);$i++){ // receive content $output = file_get_contents( $apimo_url. '?provider='.$my_provider_id. '×tamp='.$my_timestamp. '&sha1='.$apimo_sha. '&method=getAgencies'. '&type='.$apimo_type. '&version='.$apimo_version. '&agency='. '&company='.$target_company_ids[$i]. '&brand=' ); echo '<h1>Company: '.$target_company_ids[$i].'</h1>'; // remove XML declaration from results $output = substr($output, stripos($output, '?>') + 2 ); // remove leading spaces, carriage returns $output = trim($output); // convert output to XML string type $apimo = new SimpleXMLElement($output); // loop through each agency and retrieve ID foreach($apimo->agencies->agency as $agency){ echo '<h2>Agency: '.$agency->id.'</h2>'; // get properties for each agency $agency_output = file_get_contents( $apimo_url. '?provider='.$my_provider_id. '×tamp='.$my_timestamp. '&sha1='.$apimo_sha. '&method=getProperties'. '&type='.$apimo_type. '&version='.$apimo_version. '&agency='.$agency->id. '&company='. '&brand=' ); // remove XML declaration from results $agency_output = trim(substr($agency_output, stripos($agency_output, '?>') + 2 )); // convert output to XML string type $properties = new SimpleXMLElement($agency_output); foreach($properties->properties->property as $property){ echo '<h3>Property: '.$property->id.'</h3>'; echo $property->reference.'<br />'; echo $property->address.'<br />'; foreach($property->pictures->picture as $picture){ echo '<img src="'.$picture->url.'" width="150" height="100" />'; } $property_count++; } } } // end for i=0 i<count i++ // output how many properties were returned echo '<hr />Returned Properties: '.$property_count; ?>
- <?php
- // intialize a result count
- $property_count=0;
- // specify provider ID
- $my_provider_id = 1234;
- $my_timestamp = time();
- // specify company IDs
- $target_company_ids = array(2345, 3456);
- // specify target url and version
- $apimo_url = 'https://api.apimo.com/api/call';
- $apimo_version = 2;
- // specify data output
- $apimo_type = 'xml';
- // specify key and encryption
- $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234';
- $apimo_sha = sha1($apimo_key.$my_timestamp);
- //
- for($i=0;$i<count($target_company_ids);$i++){
- // receive content
- $output = file_get_contents(
- $apimo_url.
- '?provider='.$my_provider_id.
- '×tamp='.$my_timestamp.
- '&sha1='.$apimo_sha.
- '&method=getAgencies'.
- '&type='.$apimo_type.
- '&version='.$apimo_version.
- '&agency='.
- '&company='.$target_company_ids[$i].
- '&brand='
- );
- echo '<h1>Company: '.$target_company_ids[$i].'</h1>';
- // remove XML declaration from results
- $output = substr($output, stripos($output, '?>') + 2 );
- // remove leading spaces, carriage returns
- $output = trim($output);
- // convert output to XML string type
- $apimo = new SimpleXMLElement($output);
- // loop through each agency and retrieve ID
- foreach($apimo->agencies->agency as $agency){
- echo '<h2>Agency: '.$agency->id.'</h2>';
- // get properties for each agency
- $agency_output = file_get_contents(
- $apimo_url.
- '?provider='.$my_provider_id.
- '×tamp='.$my_timestamp.
- '&sha1='.$apimo_sha.
- '&method=getProperties'.
- '&type='.$apimo_type.
- '&version='.$apimo_version.
- '&agency='.$agency->id.
- '&company='.
- '&brand='
- );
- // remove XML declaration from results
- $agency_output = trim(substr($agency_output, stripos($agency_output, '?>') + 2 ));
- // convert output to XML string type
- $properties = new SimpleXMLElement($agency_output);
- foreach($properties->properties->property as $property){
- echo '<h3>Property: '.$property->id.'</h3>';
- echo $property->reference.'<br />';
- echo $property->address.'<br />';
- foreach($property->pictures->picture as $picture){
- echo '<img src="'.$picture->url.'" width="150" height="100" />';
- }
- $property_count++;
- }
- }
- } // end for i=0 i<count i++
- // output how many properties were returned
- echo '<hr />Returned Properties: '.$property_count;
- ?>
Other Methods
Here's the cURL I couldn't get working. Instead I used Apimo's documentation with file_get_contents. Just storing this in case.
// cURL With SSL via method GET: FAIL $header = array( "Content-Type: text/xml;charset=UTF-8", "Accept: gzip,deflate", "User-Agent: WWPC uAPI Test", "Cache-Control: no-cache", "Pragma: no-cache", "Connection: Keep-Alive", "Host: api.apimo.com", "Content-length: " . strlen($test_message_url), ); $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $apimo_url.'?'.$apimo_message_xml); // set url curl_setopt($ch, CURLOPT_VERBOSE, 1); // For debugging purposes (read CURL manual for nore info) curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30); // Timeout options curl_setopt($ch, CURLOPT_TIMEOUT, 30); // Timeout options curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6"); // set browser/user agent curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1); // TLS version to use (1.0) curl_setopt($ch, CURLOPT_HEADER, 0 ); // Omit headers (enable these during testing - malformed XML but more info) curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); // curl_exec function will show the response directly on the page (if set to 0 curl_exec function will return the result) curl_setopt($ch, CURLOPT_PORT, 443); // SSL port to use (443) curl_setopt($ch, CURLOPT_HEADERFUNCTION, 'read_header'); // get header $ch_result = curl_exec($ch); echo $ch_result;
- // cURL With SSL via method GET: FAIL
- $header = array(
- "Content-Type: text/xml;charset=UTF-8",
- "Accept: gzip,deflate",
- "User-Agent: WWPC uAPI Test",
- "Cache-Control: no-cache",
- "Pragma: no-cache",
- "Connection: Keep-Alive",
- "Host: api.apimo.com",
- "Content-length: " . strlen($test_message_url),
- );
- $ch = curl_init();
- curl_setopt($ch, CURLOPT_URL, $apimo_url.'?'.$apimo_message_xml); // set url
- curl_setopt($ch, CURLOPT_VERBOSE, 1);  // For debugging purposes (read CURL manual for nore info)
- curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);  // Timeout options
- curl_setopt($ch, CURLOPT_TIMEOUT, 30);  // Timeout options
- curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
- curl_setopt($ch, CURLOPT_USERAGENT, "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.1.6) Gecko/20070725 Firefox/2.0.0.6"); // set browser/user agent
- curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);  // TLS version to use (1.0)
- curl_setopt($ch, CURLOPT_HEADER, 0 );  // Omit headers (enable these during testing - malformed XML but more info)
- curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 );  // curl_exec function will show the response directly on the page (if set to 0 curl_exec function will return the result)
- curl_setopt($ch, CURLOPT_PORT, 443);  // SSL port to use (443)
- curl_setopt($ch, CURLOPT_HEADERFUNCTION, 'read_header'); // get header
- $ch_result = curl_exec($ch);
- echo $ch_result;