====== Dealer Locator Integration ======

You can use your channelAdmin partner database to drive a "dealer locator" feature on your public website, allowing your website visitors to find contact info for your partner locations in a specific geographic area.

===== Integration Options =====

We offer several different integration choices. Each has pros and cons, as described below

==== IFRAME include ====

This is the easiest way to integrate a dealer locator into your website. The basic approach is this: you supply a search form on your website (see "search parameters" section below) and POST the form to our server, specifying an HTML <iframe> on your page to display the returned results. Our server returns a fully formatted table containing the search results (or a "no dealers found" message when appropriate) which is then displayed within the <iframe> you specified. [[DL-iframe-example| sample code here]]

==== AJAX javascript include ====

In this approach, a javascript event handler is added to your form, and when the dealer locator search form is submitted an AJAX call is made from the user's browser to our server. Our server sends back an html table containing the search results, and javascript on your page inserts the table into a <div>. This method is slightly trickier to implement than the iframe approach, but the advantage is that you can use your own CSS styles to control the look of the search results table. [[DL-ajax-example| sample code here]]

==== Web Services XML API ====

In this approach, the dealer location search request is sent from your web server to ours. Our server returns the search results as an XML document rather than an HTML table. You need to supply code on your server to parse the XML and format the results into an HTML or other type of document to send back to the user's browser. This approach provides the most flexbility but requires some coding on your web server. [[DL-xml-example| sample code here]]

===== search parameters =====

The above methods differ only in how the search results are returned and then how they're presented to the end user. All of the methods use the same set of search parameters. The search parameters are "ANDed" together, so only partner locations that match all specified non-null parameters are returned. All parameters are optional. The allowable parameters are:

  * zip -- matches on postal codes. how the zip parameter is evaluated depends on how many digits are supplied:
    * 5 digits -- does a "proximity" match for partner locations within <distance> miles of the given zip code. This form is probably only useful for matching US zip codes. See also the distance parameter described below
    * less than 5 digits -- matches the leftmost digits of the location's postal code. For example, "132" will return all locations with postal codes beginning with 132. In the US (and Canada?), a 3-digit postal code match is a reliable indicator of proximity. 
  * distance -- used in conjunction with 5-digit zip code proximity search (see "zip" parameter above). Units: miles.
  * state -- this parameter should contain the integer state or province code in supported countries (US, Canada, and Mexico are supported, and others may be supported in your installation on request). You can get a list of supported state/province codes by running the "state/province list" services described in the [[api_helper_functions]] section
  * partnerTags -- match locations that belong to partners who are tagged with the given tag. The parameter value must be the integer tag ID -- contact the support team for a list of valid partnerTags values in your installation
  * tags -- match locations that are tagged with the given location tag. The parameter value must be the integer tag ID -- contact the support team for a list of valid location tag ID values in your installation
  * city -- a substring match on the location's city name
  * country -- matches the integer country code for the location. examples: US=1,Canada=30. You can get a complete list of country codes by running the "country list" service described in the [[api_helper_functions]] section

===== limitations =====

A dealer locator search will return a limited number of results. The limit is set as an installation "AppConfig" variable, and is intended to make it more difficult (but not impossible) for someone to retrieve your entire partner database. The default limit is 50. If you'd like it changed in your installation please contact tech support.