Dealer Locator API

Overview

The Dealer Locator API returns a list of dealers near a postal code, sorted by distance. Use it to power dealer finder pages on websites and apps. The response includes group identifiers so you can collapse multi-unit dealer groups on the client side.

How It Works

Each brand maintains a territory map — a list of postal codes pre-assigned to specific dealers. When you call the API, the following priority chain determines what comes back:

1. Territory match — if the queried postal code is assigned to a dealer in the territory map, that dealer is always returned first (match_type: "territory", index 0), regardless of distance. This is the authorised dealer for that area.
2. Distance results — all other active dealers within max_distance_miles are returned sorted by proximity (match_type: "distance"). For non-US/CA countries, all dealers in the country are returned with no distance cap.
3. Group siblings — if a dealer in the results belongs to a multi-location group (group_id), any other locations from the same group that weren't already included are automatically appended (match_type: "group_sibling"). This ensures the caller always sees every location of a dealer company, even if some are outside the distance radius.
4. Global fallback — for non-US/CA queries that find zero dealers in the country, the brand's designated fallback contact (e.g. a headquarters or importer) is returned (match_type: "fallback").

Endpoint

Authentication

Requests require the X-API-Token header with your API token:

X-API-Token: your_api_token_here

Parameters

Example Request

curl -X GET "https://api.marquatica.com/dealer-locator?brand=your_brand&postal_code=28117&country=US&limit=5" \
  -H "X-API-Token: your_api_token_here"

Success Response

Dealers Found

{
  "dealers": [
    {
      "address": "123 Marina Drive",
      "address2": "",
      "city": "Lakeside",
      "country": "USA",
      "dealer_code": "1001-1",
      "distance_miles": 3.2,
      "email": "info@lakesidemarine.com",
      "group_id": 1001,
      "group_name": "Lakeside Marine Group",
      "id": 101,
      "latitude": 35.5001,
      "legal_name": "",
      "logo_url": "",
      "longitude": -80.85,
      "match_type": "territory",
      "name": "Lakeside Marine Group",
      "phone": "(555) 123-4567",
      "postal_code": "28117",
      "primary_contact": "",
      "state": "NC",
      "territory_match": true,
      "unit_id": 1,
      "website": "https://www.lakesidemarine.com"
    },
    {
      "address": "456 Waterfront Blvd",
      "address2": "",
      "city": "Hillside",
      "country": "USA",
      "dealer_code": "1001-2",
      "distance_miles": 87.5,
      "email": "info@lakesidemarine.com",
      "group_id": 1001,
      "group_name": "Lakeside Marine Group",
      "id": 102,
      "latitude": 36.12,
      "legal_name": "Lakeside Marine LLC",
      "logo_url": "",
      "longitude": -81.23,
      "match_type": "group_sibling",
      "name": "Lakeside Marine - Hillside",
      "phone": "(555) 987-6543",
      "postal_code": "28031",
      "primary_contact": "",
      "state": "NC",
      "territory_match": false,
      "unit_id": 2,
      "website": "https://www.lakesidemarine.com"
    }
  ],
  "success": true,
  "version": "0.2.0"
}

No Dealers Found

{
  "success": true,
  "version": "0.2.0",
  "dealers": []
}

Response Fields

Ordering Rules

• US / CA: territory match is always at index 0 (if one exists), followed by dealers within max_distance_miles sorted by ascending distance, truncated to limit.
• Other countries: max_distance_miles and limit are ignored. All active dealers in the queried country are returned sorted by distance, guaranteeing no dealer is missed regardless of geography.
• Group siblings — after the primary list is built, any dealer sharing a group_id with an included dealer (but not yet in the list) is appended as match_type: "group_sibling", bypassing all filters.
• Fallback — for non-US/CA queries that return zero dealers, the brand's designated global fallback dealer is appended as match_type: "fallback".

Grouping Dealers on the Client

Some dealer companies operate multiple physical locations (units). They share the same group_id and have distinct unit_id values. The API returns one row per unit sorted by distance. To display a single card per company with selectable locations, group the results client-side by group_id (or by id for solo dealers with no group).

Error Response Examples

Missing Brand Parameter

{
  "error": "Brand parameter is required",
  "version": "0.2.0"
}

Invalid Postal Code Format

{
  "error": "Invalid US postal code format. Must be exactly 5 digits (e.g., 12345)",
  "version": "0.2.0"
}

Invalid Country Code

{
  "error": "Invalid country code. Use US or CA",
  "version": "0.2.0"
}

Invalid limit

{
  "error": "limit must be an integer",
  "version": "0.2.0"
}

Country Code Support

Notes

• Distances are calculated using the Haversine formula.
• Only dealers in the same country as the searched postal code are returned.
• Only active dealers with stored coordinates are included in results.
• The territory match is preserved at index 0 even when filtered out by max_distance_miles.