Overview

The Dealer Locate API will return data for dealer locations.

There are three implementation options for the Dealer Locate API. 

• Standard dealer location option will treat all dealers as equally weighted in the search results it returns. 
• Priority-based ranking of dealers by each brand they carry. This option allows the caller to filter out dealers based on brand priority values. If you are using the brand priority option, you must define the BrandCode and the CustomTerms: MinimumPriority and MaximumPriority.
• Inventory-based ranking of dealers by matching product details to actual inventory items in stock. Dealers that match based on their inventory will have a MatchType of "Inventory".  If there are no inventory based matches or not enough results to fulfillment take parameter, other dealers will be included and the dealer locate rule applied will be indicated in the MatchType value.

Possible Response Codes

• 201 (Created). This response indicates that the dealer territory data was successfully parsed. The body of the response will contain the success or failure status for each item that was submitted in the request. NOTE: The response record details for each item will be returned in the order that they were submitted.
• 400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request. See example response posts for the structure of the error response.
• 500 (Internal Server Error). An unknown error occurred during the import.

Authentication

The Dealer Locate API requires authentication so the HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token. 

Authenticate message header example:

Authenticate: Avala-Api {username}:{token}

Post Information

HTTP Endpoint

http://{baseurl}/Marketing/api/LocatedDealerSearch?manufacturer={manufacturercode}

Dealer Data Schema 

Terms Data Schema 

Custom Term Data Schema 

Custom Term Values

The values below are the current custom terms supported by the API for the priority based dealer locate option.

The values below are the current custom terms supported by the API for Inventory based dealer locate option.

Note: Service Endpoint Behavior

There are some qualifications that a dealer in Aimbase must meet to be included in a response:

• Manufacturer: the dealer’s manufacturer must match the manufacturer sent on the API post
• Dealer Type: the dealer must have a selected value of “Standard Dealer”
• Active For: the dealer must have a selected value of “Both”
• Active: the dealer must be set as Active – Yes.

In addition to having the values selected above, there needs to be enough location data on the dealer details or some assigned territories. Without this, the dealer will be omitted from the locate results, because their location or coverage is unknown.

XML Example Post

POST: http://{baseurl}/Marketing/api/LocatedDealerSearch?manufacturer={manufacturercode} 
Host: {baseurl} 
Authenticate: Avala-Api {username}:{token} 
Content-Type: application/xml
 
<LocatedDealerRequest>
  <Skip>0</Skip>
  <Take>1</Take>
  <Terms>
    <ManufacturerCode>M0001</ManufacturerCode>
    <CountryCode>US</CountryCode>
    <PostalCode>90210</PostalCode>
    <IncludeAllInDealerGroup>true</IncludeAllInDealerGroup>
  </Terms>
</LocatedDealerRequest>

XML Example Response

<ArrayOfLocatedDealerModel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <LocatedDealerModel>
    <Id>5</Id>
    <Name>Midwest Boats</Name>
    <DealerNumber>0005</DealerNumber>
    <DealerLocation>1</DealerLocation>
    <DealerTypeCode>S</DealerTypeCode>
    <DealerTypeName>Standard Dealer</DealerTypeName>
    <Address>
      <Address1>123 Main Street</Address1>
      <City>New York</City>
      <State>NY</State>
      <PostalCode>10004</PostalCode>
      <CountryCode>US</CountryCode>
    </Address>
    <Email>dealer@aimbase.com</Email>
    <Phone>3146209191</Phone>
    <Latitude>40.704169</Latitude>
    <Longitude>-74.012311</Longitude>
    <Distance>3956175.7651729658</Distance>
    <DistanceMiles>2458.3 mi</DistanceMiles>
    <DistanceKilometers>3956.2 km</DistanceKilometers>
    <Priority>0</Priority>
    <IsInMarket>true</IsInMarket>
    <DealerGroupCode>0005</DealerGroupCode>
    <DealerGroupName>Midwest Boats</DealerGroupName>
    <BrandsInDealer>
        <string>BrandA</string>
    </BrandsInDealer>
    <MatchType>Default</MatchType>
  </LocatedDealerModel>
</ArrayOfLocatedDealerModel>

JSON Example Post

POST: http://{baseurl}/Marketing/api/LocatedDealerSearch?manufacturer={manufacturercode} 
Host: {baseurl} 
Authenticate: Avala-Api {username}:{token} 
Content-Type: application/json
 
{
   "Skip":"0",
   "Take":"1",
   "Terms":{
      "ManufacturerCode":"M0001",
      "CountryCode":"US",
      "PostalCode":"90210",
      "IncludeAllInDealerGroup":true,
   }
}

JSON Example Response

[
   {
      "Id":5,
      "Name":"Midwest Boats",
      "DealerNumber":"0005",
      "DealerLocation":"1",
      "DealerTypeCode":"S",
      "DealerTypeName":"Standard Dealer",
      "Address":{
         "Address1":"123 Main Street",
         "Address2":null,
         "City":"New York",
         "State":"NY",
         "PostalCode":"10004",
         "County":null,
         "CountryCode":"US",
         "Country":null
      },
      "Email":"dealer@aimbase.com",
      "Phone":"3146209191",
      "Fax":null,
      "WebsiteUrl":null,
      "Latitude":40.704169,
      "Longitude":-74.012311,
      "Distance":3956175.7651729658,
      "DistanceMiles":"2458.3 mi",
      "DistanceKilometers":"3956.2 km",
      "Priority":0,
      "DealerGroupCode":"0005",
      "DealerGroupName":"Midwest Boats",
      "IsInMarket":true,
      "BrandsInDealer": [ 
        "BrandA"
      ],
      "MatchType" : "Default"
   }
]

Example Failed Response (XML/JSON)

The error response below indicates a required field was left out.

XML:

<Error>
  <Message>The ManufacturerCode field is required.</Message>
</Error>

JSON: 

{
   "Message":"The ManufacturerCode field is required."
}

The error response below indicates that the data submitted could not be parsed into the correct format.

XML:

<LocatedDealerModel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Message>Bad request: There is an error in XML document (1, 1).</Message>
</LocatedDealerModel>

JSON:

{
   "Message":"An unhandled error occurred. Object reference not set to an instance of an object."
}