Public Inventory Source
The inventory source fetches active dealer inventory from the Stellantis brand public web APIs
(jeep.com, dodge.com, ramtrucks.com, chrysler.com). It is specific to the Stellantis
project (projects/ai_stellantis).
Endpoint Pattern
https://www.<brand-domain>/hostd/inventory/getinventoryresults.json
Pagination uses pageNumber (1-based) and pageSize query params. Total record count is read
from result.data.metadata.totalcount in the first page response.
Required Environment Variables
| Variable | Default | Description |
|---|---|---|
STELLANTIS_INVENTORY_ZIP | 66952 | Center ZIP code for inventory radius search |
STELLANTIS_INVENTORY_RADIUS | 5000 | Search radius in miles |
STELLANTIS_INVENTORY_PAGES_WORKERS | 10 | Concurrent page fetch workers |
STELLANTIS_INVENTORY_TIMEOUT | 60.0 | Per-request timeout in seconds (covers connect + read) |
STELLANTIS_INVENTORY_MAX_RETRIES | 3 | Retries per page on transient errors (429/5xx, connection errors, read timeouts) |
STELLANTIS_INVENTORY_RETRY_BACKOFF | 2.0 | Initial backoff in seconds; doubles each attempt |
STELLANTIS_INVENTORY_MAX_PER_MODEL | (unset) | Cap total records per model year code (dev/testing) |
Authentication
No credentials required. The endpoint is a public API used by the Stellantis brand consumer
websites. Requests use browser-impersonating headers (random_headers() from ai_core.http_utils).
Known Data Quality Issues
Incorrect brand field on Jeep vehicles
The Jeep inventory API occasionally returns a small number of records (~7 per affected day) where
the brand field contains a non-Stellantis value such as "Toyota", "Ford", or "Lexus".
Inspection of the affected records confirms these are genuine Jeep vehicles — VINs start with
1C4 (Chrysler/Jeep WMI) and the Stellantis-internal extImage/intImage fields carry
brand=J. The corrupted brand value originates in the Stellantis backend and is returned
verbatim by the API.
Impact: COSY image URL generation requires a valid Stellantis brand. An unknown brand
previously caused a KeyError crash that blocked the transformed asset for ~60 affected
partition dates over the year.
Fix applied: make_cosy_image_urls in ai_stellantis/cosy.py validates the brand against
the set of values accepted by the COSY generator (StellantisBrand Literal type). Records with
an unrecognized brand are written to the output with null image URLs and a warning is logged;
the partition does not fail.
If the upstream data quality improves or a reliable correction rule can be determined from the VIN WMI prefix, this behavior can be revisited.