Dealer Locate API

Overview

The Dealer Locate API will return data for dealer locations.

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.

Options

There are two implementation options for the Dealer Locate API. A standard dealer location option will treat all dealers as equally weighted in the search results it returns. The other option is a 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.

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 

Field Name  Required  Format  Description 
Terms X Terms Data Schema The search criteria for the dealers to return in the located results. Can include properties for manufacturer, brand, country, state, postal code, and a collection of custom name/value pair search terms.  (See Terms Data Schema below)
Skip
Integer The number of dealer located results to skip when building the response.
Take
Integer The number of dealer located results to return in a single response.

Terms Data Schema 

Field Name  Required  Format  Description 
ManufacturerCode X Max Length: 6 The manufacturer code used to restrict the dealer located response results.
DealerTypeCode
Max Length: 20 The dealer code used to restrict the dealer located response results. NOTE: This can support multiple values by comma or semicolon delimiting the values. Example: “V,B” to return dealers from 2 different dealer types.
BrandCode (only for priority dealer locate option) Max Length: 48 The brand code used to restrict the dealer located response results.  NOTE: it is required when searching based on dealer priority by brand settings.
CountryCode X Max Length: 2 ISO ALPHA-2 country code
State
Max Length: 50 State code or abbreviation
PostalCode
Max Length: 10 Zip or Postal Code depending on the country.
Latitude
Decimal
Longitude
Decimal
IncludeAllInDealerGroup
true/false If the responses should include all dealers in the dealer groups that are found.
CustomTerms
Collection/Array of Custom Term Data Schema Additional data arguments that can be configured for custom dealer locate applications.  Not in use with the standard dealer locate API.

Custom Term Data Schema 

Field Name  Required  Format  Description 
Name X String The name of the custom search term.
Value X String The value to be applied to the dealer located results search.

Custom Term Values

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

Field Name  Format  Description 
MinimumPriority Integer Required when searching for and ranking dealer locate results based on the dealer priority by brand setting.
MaximumPriority Integer Required when searching for and ranking dealer locate results based on the dealer priority by brand setting.

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."
}