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​

None. 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 limit results to it. With a large enough count it returns every US dealer, about 387, whatever zip is supplied. The source therefore passes a fixed placeholder zip and a large count. A sweep over zip codes would multiply the 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 runs once per dealer and gives one raw row per dealer, so the IO manager streams the rows instead of holding the national result set in memory.
  3. GET /vehicles/lookup/vin?vin={vin} adds colors, images, engine specs, features and packages to each VIN.

One pagination of a dealer misses some of its VINs​

The search service orders a dealer's vehicles by price, and it breaks ties between equal prices differently on each request. A vehicle can therefore move between pages while the pages are fetched, so it appears on two pages or on none. One pagination of a large dealer misses up to about 4% of the VINs its totalCount reports, and each pagination misses different ones; dealer 14316, with 819 vehicles, returned between 783 and 804. In daily snapshots, those VINs seem to leave and return.

The sortBy parameter accepts only price and distance; omitting it also works. No ordering is stable. A pagination by price and one without sortBy miss about as many VINs, but different ones. A page size above 100 returns a 500.

Akamai caches every search page until 09:00 UTC​

Responses include Cache-Control: public, max-age=… and an Expires header set to the next 09:00 UTC, and Akamai caches each URL until then. A repeated request for the same URL returns the cached page, so paginating a dealer again with the same parameters returns the same VINs. The pages of one dealer can also come from cache entries filled at different times.

Every search and dealer-list request therefore sends a _ parameter with a value unique to the pagination. The service ignores the parameter, and Akamai forwards the request to the service instead of answering from its cache.

Dealers short of their totalCount are paginated again​

fetch_inventory_search paginates every dealer once. It then paginates again each dealer whose distinct VINs, across all paginations so far, are fewer than the totalCount of its latest pagination. Passes alternate between sorting by price and sending no sortBy, so a VIN that one ordering keeps placing between pages can appear under the other. It waits pass_interval_seconds between passes and stops after max_passes passes or once no dealer is short. A dealer whose search fails is also retried in the next pass.

The check counts VINs, not which VINs. A dealer that sold one vehicle and received another between two passes reaches its totalCount while the new vehicle is still missing.

Every pass's pages are written to nafta_inventory_search, so a VIN can appear on several rows. nafta_inventory_vin looks up each distinct VIN once.

Some vehicle records have no dealer object​

Each day, a few vehicle records in the search results have no dealer object. extract_dealers_from_inventory skips such a record.

The service's totals vary overnight​

The totalCount the service reports for a dealer also changes by more than pagination explains. Between about 00:00 and 04:00 UTC, some dealers report 10% to 15% fewer vehicles for up to an hour and then return to their earlier count; dealer 14316 reported 716 against its usual 817. The raw assets run at 00:00 UTC, so a run can read a dealer during such a drop. Paginating again does not detect it, because the dealer's totalCount drops with its results.

Baumuster and option codes come from the COSY image URL​

A vehicle's 6-digit baumuster is the eighth path segment of its COSY image URL. Option codes are extracted by COSY-decoding the URL's COSY string. URL decoding is skipped, because % is a valid character in COSY encoding.

The COSY string is in one of two places in the URL's query string:

  • the value of q, in media.oneweb.mercedes-benz.com/images/dynamic/nafta/US/... URLs (?q=COSY-EU-...);
  • a query part without a parameter name, in the nafta.starconnect-ce.i.mercedes-benz.com/iris/iris.jpg URLs of payloads from before mid-2026 (?COSY-EU-...&IMGT=...). In these payloads, the paint and upholstery ids are empty strings. The path of these URLs has no baumuster, so these vehicles have none.

The VIN lookup returns UNDEFINED as the paint or upholstery id of some vehicles, such as those with MANUFAKTUR colors. Their COSY URL still names both: LU holds the paint code and AU the upholstery code. For some models COSY appends a letter to the code: U to paint and A to upholstery (885U, 961A), and for others it does not (885, 961). The transformed tier removes that letter. It also drops every UNDEFINED id. When the lookup then has no paint (2:) or no upholstery (4:) id, because the field is UNDEFINED or absent, the transformed tier takes that code from LU or AU. A vehicle without a COSY URL, or whose URL does not decode, gets no paint or upholstery from it.

Option id formats differ between endpoints​

The VIN lookup returns option ids with dashes, and the NAFTA configurator returns the same ids with colons. The transformed tier rewrites them to the colon form before joining.

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

Locale format​

The configurator's locale segment is en_us, with an underscore. The endpoint accepts a hyphenated locale but returns an empty class list instead of an error.

Base codes on NAFTA inventory​

On some model lines, a NAFTA vehicle lists the model's base wheel or interior trim beside the one the buyer chose. A C 300 with the 19" RVD wheel lists RSK and RVC as well. NetSTAR lists only the chosen code. Featurization then gives the vehicle two values of a multiclass scheme, such as WHEEL_DIAMETER.

Before it adds tires, MercedesNaftaInventoryComponent drops the base code. The rules that name each base code are in the nafta_feature_co_occurrence_removals template var. Each rule names a model pattern, the chosen code (if_present) and the base code (drop). A vehicle that lists only the base code keeps it.

A pair gets a rule when either holds:

  • On at least three VINs that NAFTA listed first and NetSTAR listed later, NetSTAR keeps the chosen code and drops the base code. NetSTAR never keeps the base code and drops the chosen code. The one exception is the C 300 pair of RVD and RVC. On two VINs, NetSTAR keeps RVC and drops RVD.
  • NAFTA lists the chosen code on at least three vehicles of the model, always together with the base code, and NetSTAR never lists the two together. On the GLC 53 coupe, NAFTA lists RWL only with RVM, while NetSTAR lists RWL alone.

The rules leave out:

  • the G-Class wheels, for which NetSTAR keeps the chosen code on some VINs and the base code on others;
  • pairs whose chosen code NetSTAR never lists, such as H85 on the CLA 45;
  • RR3 (spare-wheel cover) and U61 (MANUFAKTUR Leather package), which a vehicle has together with a wheel or headliner.

The base code depends on the model year. On the GLE 350, RYA is the base wheel in MY2026 and a chosen wheel in MY2027. A rule therefore names the pair, not only the base code.