====== Dealer Locator XML API ======

===== Overview =====

This "web service" (we're using that term pretty loosely) accepts an HTTP POST pretty much identical to the ones posted from a browser in the Iframe and Ajax approaches. However, it's assumed that this POST will be submitted by your server rather than your user's browser, and the results are returned as an XML data structure. You can then exercise your favorite XML parser and use the resulting structured data to generate formatted results in, for example PHP, a perl CGI, Java, or Rails/Ruby.

===== Sample XML Search Results =====

We don't have any formal WSDL. Here's what the XML looks like:
<code XML>
<?xml version="1.0" encoding="UTF-8"?>
<locations>
    <location>
        <street1>de La Gauchetière Oues</street1>
        <city>Montreal</city>
        <stateProvinceCode>11</stateProvinceCode>
        <stateProvince>Quebec</stateProvince>
        <zip>H3B 4Y7</zip>
        <countryCode>30</countryCode>
        <country>Canada</country>
        <partnerName>Allianz Limited</partnerName>
        <hq_flag>N</hq_flag>
        <phone/>
        <fax/>
        <label>Montreal</label>
    </location>
    <location>
        <street1>458 First Street</street1>
        <city>Vancouver</city>
        <stateProvinceCode>2</stateProvinceCode>
        <stateProvince>British Columbia</stateProvince>
        <zip>V6Z 1Z7</zip>
        <countryCode>30</countryCode>
        <country>Canada</country>
        <partnerName>Allianz Limited</partnerName>
        <hq_flag>Y</hq_flag>
        <phone>(541) 338-2234</phone>
        <fax/>
        <label>Main Office</label>
    </location>
...etc...

</code>

===== Example Perl Application =====

here's a simple perl app that calls the web service and parses the XML result into a perl data structure. 

<code perl>
#!/usr/bin/perl
use strict;
use LWP::UserAgent;
use HTTP::Request;
use XML::Simple;
 
my $params='?country=30';  # for testing, we'll look for dealers in canada
my $baseurl='http://<your channelsuite URL>/API/DealerLocator/xml.cgi';

my $agent = LWP::UserAgent->new(env_proxy => 1,keep_alive => 1, timeout => 30);
my $url = $baseurl.$params;  # a GET URL string
my $header = HTTP::Request->new(GET => $url);
my $request = HTTP::Request->new('GET', $url, $header);
 
# send HTTP GET request and get response object
my $response = $agent->request($request);	
 
my $data;
if ($response->is_success) {
   my $xmlStream = $response->content;
   print "received XML : $xmlStream\n";
   my $xmlObject = new XML::Simple;
   $data = $xmlObject->XMLin($xmlStream);	# parse XML
} else {
  die $response->status_line;
}

use Data::Dumper;  # handy perl module for dissecting your data structures
print Dumper $data;  # $data includes an arrayref of hashrefs with xml fields

# now do something useful with it...
</code>