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
| Source | Endpoint |
|---|---|
models | GET mbusa.com/content/public-api/vd/active-models |
features | GET nafta-service.mbusa.com/api/byo/v1/{locale}/{class}/{model}/{year} |
dealers | GET nafta-service.mbusa.com/api/dlrsrv/v1/us/search |
inventory | GET 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:
GET /dealersreturns the dealer ids that have inventory.GET /vehiclesruns 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.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, inmedia.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.jpgURLs 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
RVDandRVC. On two VINs, NetSTAR keepsRVCand dropsRVD. - 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
RWLonly withRVM, while NetSTAR listsRWLalone.
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
H85on the CLA 45; RR3(spare-wheel cover) andU61(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.