Accessing Apimo WebService API

Applies to:
  • Apimo Webservice 2.0 (apimo.com)
  • PHP v5.5
What?
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):
copyraw
// 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;
}
  1.  // specify provider ID 
  2.  $my_provider_id = 1234
  3.  $my_timestamp = time()
  4.   
  5.  // specify company ID 
  6.  $company_id_1 = 1234
  7.  $company_id_2 = 4321
  8.   
  9.  // specify agency ID 
  10.  $company_id_1_agency_id = ''
  11.  $company_id_1_brand_id = ''
  12.   
  13.  // specify target url and version 
  14.  $apimo_url = 'https://api.apimo.com/api/call'
  15.  $apimo_version = 2
  16.   
  17.  // specify data output 
  18.  $apimo_method = 'getAgencies'
  19.  $apimo_type = 'xml'
  20.   
  21.  // specify key and encryption 
  22.  $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234';  // specify your assigned key here 
  23.  $apimo_sha = sha1($apimo_key.$my_timestamp)
  24.   
  25.  // receive content 
  26.  $output = file_get_contents( 
  27.          $apimo_url
  28.          '?provider='.$my_provider_id
  29.          '×tamp='.$my_timestamp
  30.          '&sha1='.$apimo_sha
  31.          '&method='.$apimo_method
  32.          '&type='.$apimo_type
  33.          '&version='.$apimo_version
  34.          '&agency='.$company_id_1_agency_id
  35.          '&company='.$company_id_1
  36.          '&brand='.$company_id_1_brand_id 
  37.  )
  38.   
  39.  // remove XML declaration from results 
  40.  $output = substr($output, stripos($output, '?>') + 2 )
  41.   
  42.  // remove leading spaces, carriage returns 
  43.  $output = trim($output)
  44.   
  45.  // process if type specified was xml 
  46.  if($apimo_type=='xml'){ 
  47.   
  48.          // send header 
  49.          header("Content-Type:text/xml")
  50.   
  51.          // print result to page 
  52.          echo $output
  53.  } 
Advanced Example
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:
copyraw
<?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;
?>
  1.  <?php 
  2.   
  3.  // intialize a result count 
  4.  $property_count=0
  5.   
  6.  // specify provider ID 
  7.  $my_provider_id = 1234
  8.  $my_timestamp = time()
  9.   
  10.  // specify company IDs 
  11.  $target_company_ids = array(2345, 3456)
  12.   
  13.  // specify target url and version 
  14.  $apimo_url = 'https://api.apimo.com/api/call'
  15.  $apimo_version = 2
  16.   
  17.  // specify data output 
  18.  $apimo_type = 'xml'
  19.   
  20.  // specify key and encryption 
  21.  $apimo_key = 'abcd1234abcd1234abcd1234abcd1234abcd1234'
  22.  $apimo_sha = sha1($apimo_key.$my_timestamp)
  23.   
  24.  // 
  25.  for($i=0;$i<count($target_company_ids);$i++){ 
  26.   
  27.          // receive content 
  28.          $output = file_get_contents( 
  29.                  $apimo_url
  30.                  '?provider='.$my_provider_id
  31.                  '×tamp='.$my_timestamp
  32.                  '&sha1='.$apimo_sha
  33.                  '&method=getAgencies'
  34.                  '&type='.$apimo_type
  35.                  '&version='.$apimo_version
  36.                  '&agency='
  37.                  '&company='.$target_company_ids[$i]
  38.                  '&brand=' 
  39.          )
  40.   
  41.          echo '<h1>Company: '.$target_company_ids[$i].'</h1>'
  42.   
  43.          // remove XML declaration from results 
  44.          $output = substr($output, stripos($output, '?>') + 2 )
  45.   
  46.          // remove leading spaces, carriage returns 
  47.          $output = trim($output)
  48.   
  49.          // convert output to XML string type 
  50.          $apimo = new SimpleXMLElement($output)
  51.   
  52.          // loop through each agency and retrieve ID 
  53.          foreach($apimo->agencies->agency as $agency){ 
  54.   
  55.          echo '<h2>Agency: '.$agency->id.'</h2>'
  56.   
  57.                  // get properties for each agency 
  58.                  $agency_output = file_get_contents( 
  59.                          $apimo_url
  60.                          '?provider='.$my_provider_id
  61.                          '×tamp='.$my_timestamp
  62.                          '&sha1='.$apimo_sha
  63.                          '&method=getProperties'
  64.                          '&type='.$apimo_type
  65.                          '&version='.$apimo_version
  66.                          '&agency='.$agency->id. 
  67.                          '&company='
  68.                          '&brand=' 
  69.                  )
  70.   
  71.                  // remove XML declaration from results 
  72.                  $agency_output = trim(substr($agency_output, stripos($agency_output, '?>') + 2 ))
  73.   
  74.                  // convert output to XML string type 
  75.                  $properties = new SimpleXMLElement($agency_output)
  76.   
  77.                  foreach($properties->properties->property as $property){ 
  78.                          echo '<h3>Property: '.$property->id.'</h3>'
  79.                          echo $property->reference.'<br />'
  80.                          echo $property->address.'<br />'
  81.                          foreach($property->pictures->picture as $picture){ 
  82.                                  echo '<img src="'.$picture->url.'" width="150" height="100" />'
  83.                          } 
  84.                          $property_count++
  85.                  } 
  86.   
  87.          } 
  88.   
  89.  } // end for i=0 i<count i++ 
  90.   
  91.  // output how many properties were returned 
  92.  echo '<hr />Returned Properties: '.$property_count
  93.  ?> 

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.
copyraw
// 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;
  1.  // cURL With SSL via method GET: FAIL 
  2.  $header = array( 
  3.  "Content-Type: text/xml;charset=UTF-8", 
  4.  "Accept: gzip,deflate", 
  5.  "User-Agent: WWPC uAPI Test", 
  6.  "Cache-Control: no-cache", 
  7.  "Pragma: no-cache", 
  8.  "Connection: Keep-Alive", 
  9.  "Host: api.apimo.com", 
  10.  "Content-length: " . strlen($test_message_url), 
  11.  )
  12.  $ch = curl_init()
  13.  curl_setopt($ch, CURLOPT_URL, $apimo_url.'?'.$apimo_message_xml)// set url 
  14.  curl_setopt($ch, CURLOPT_VERBOSE, 1);                              // For debugging purposes (read CURL manual for nore info) 
  15.  curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);                      // Timeout options 
  16.  curl_setopt($ch, CURLOPT_TIMEOUT, 30);                             // Timeout options 
  17.  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false)
  18.  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 
  19.  curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1);       // TLS version to use (1.0) 
  20.  curl_setopt($ch, CURLOPT_HEADER, 0 );                              // Omit headers (enable these during testing - malformed XML but more info) 
  21.  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) 
  22.  curl_setopt($ch, CURLOPT_PORT, 443);                               // SSL port to use (443) 
  23.  curl_setopt($ch, CURLOPT_HEADERFUNCTION, 'read_header')// get header 
  24.  $ch_result = curl_exec($ch)
  25.   
  26.  echo $ch_result
Category: API Miscellaneous :: Article: 638

Credit where Credit is Due:


Feel free to copy, redistribute and share this information. All that we ask is that you attribute credit and possibly even a link back to this website as it really helps in our search engine rankings.

Disclaimer: The information on this website is provided without warranty and any content is merely the opinion of the author. Please try to test in development environments prior to adapting them to your production environments. The articles are written in good faith and, at the time of print, are working examples used in a commercial setting.

Thank you for visiting and, as always, we hope this website was of some use to you!

Kind Regards,

Joel Lipman
www.joellipman.com

Related Articles

Joes Revolver Map

Joes Word Cloud

Accreditation

Badge - Certified Zoho Creator Associate
Badge - Certified Zoho Creator Associate

Donate & Support

If you like my content, and would like to support this sharing site, feel free to donate using a method below:

Paypal:
Donate to Joel Lipman via PayPal

Bitcoin:
Donate to Joel Lipman with Bitcoin - Valid till 8 May 2022 3QnhmaBX7LQSRsC9hh6Je9rGQKEGNQNfPb
© 2021 Joel Lipman .com. All Rights Reserved.