Skip to main content

NAFTA Public API Source

The NAFTA sources fetch models, features, dealers and inventory from the public Mercedes-Benz USA web APIs. The client modules live in packages/ai_public_api/src/ai_public_api/mercedes/nafta/.

Authentication​

No credentials required. All four endpoints are public.

Endpoints​

SourceEndpoint
modelsGET mbusa.com/content/public-api/vd/active-models
featuresGET nafta-service.mbusa.com/api/byo/v1/{locale}/{class}/{model}/{year}
dealersGET nafta-service.mbusa.com/api/dlrsrv/v1/us/search
inventoryGET nafta-service.mbusa.com/api/inv/v1/en_us/new/...

Dealer search returns the national list​

The dealer search endpoint accepts a zip parameter but does not scope results to it. With count set high enough it returns every US dealer (~387) regardless of the zip supplied, so the source passes a fixed placeholder zip and a large count rather than sweeping zip codes.

Do not "fix" the hardcoded zip into a sweep: it would multiply requests without widening coverage.

Inventory is fetched per dealer, then enriched per VIN​

Inventory runs in three phases:

  1. GET /dealers returns the dealer ids that have inventory.
  2. GET /vehicles is called once per dealer, yielding one raw row per dealer so the IO manager can stream them rather than holding the national result set in memory.
  3. GET /vehicles/lookup/vin?vin={vin} enriches each VIN with colors, images, engine specs, features and packages.

Baumuster and SA codes come from the COSY image URL​

A vehicle's 6-digit baumuster is the eighth path segment of its embedded COSY image URL. The SA (Sonderausstattung) option codes are read from that URL's q parameter without URL-decoding it first, because % is a valid COSY charset character — decoding corrupts the code list.

Option id formats differ between endpoints​

The VIN lookup returns option ids with dashes; the BYO (Build Your Own) configurator returns the same ids with colons. The transformed tier normalizes to the colon form before joining.

Some fields are also typed differently between the two: the VIN lookup returns {"name": ...} objects where the search endpoint returns plain strings.

Locale format​

The BYO locale segment is en_us, with an underscore. A hyphenated locale is accepted by the endpoint but silently returns an empty class list rather than an error.