Genesis US Public API Sources

The ai_genesis pipeline uses four public API endpoints — no authentication credentials are required. All require a Referer: https://www.genesis.com/ header except the dealer list, which is hosted on hyundaiusa.com and requires browser TLS impersonation to pass Cloudflare.

Endpoints

Source	Resource	Method	URL
inventory_search	inventory	GET	https://www.genesis.com/bin/api/v2/inventory/search
dealer_list	dealers	GET	https://www.hyundaiusa.com/var/hyundai/services/dealer.allDealers.service
vehicle_catalog	models	GET	https://www.genesis.com/bin/api/v2/vehicles
vehicle_configurator	configurator	GET	https://www.genesis.com/bin/api/v2/vehicle/byo + https://www.genesis.com/bin/api/v2/vehicle/trims

Inventory Search

The inventory search API returns all national inventory for a single model name in one response (no pagination). A per-model sweep is required because model=all returns zero vehicles. The fetch function:

1. Calls /bin/api/v2/vehicles to get the current model list (falls back to a hardcoded list of 8 names if that request fails).
2. Fans out one GET per model concurrently with parallel_call (max_workers=4).
3. Stores one raw row per model; _request_params contains {"model": "<name>"} and _response_body contains the JSON-encoded vehicles array for that model.

Query parameters: zip=10001, model=<model_name>, distance=5000

Response shape: result.vehicles[] — array of vehicle objects with VIN, DealerCd, DlrName, Address1, City, State, DlrZipCode, Phone, SAPModelCd, ModelGroupCd, ModelYear, TrimDesc, Model, Drivetrain, EngineDesc, Trans, SortablePrice, ExtColorCd, ExtColorDesc, IntColorCd, IntColor, Mileage, PlannedDeliveryDate.

Note: SAPModelCd is a powertrain-level code (e.g. V0432A45); Mileage carries the inventory status value ("New" for new vehicles).

Three entity types are extracted from the same raw asset via the registry:

• (inventory_search, inventory, inventory) → extract_inventory
• (inventory_search, inventory, dealers) → extract_dealers_from_inventory
• (inventory_search, inventory, models) → extract_models_from_inventory

Inventory records use SAPModelCd as model_code (powertrain-level granularity). The consolidated model FK join uses (model_code, model_year).

Dealer List

The allDealers API is shared with Hyundai US. Passing brand=genesis returns the ~199 Genesis dealers rather than the ~861 Hyundai dealers. A single request returns all dealers with no geographic filtering.

URL: https://www.hyundaiusa.com/var/hyundai/services/dealer.allDealers.service

Query parameters: brand=genesis, model=all, lang=en

Auth: The endpoint is hosted on hyundaiusa.com and sits behind Cloudflare. The fetch function uses browser_session(seed_url="https://www.hyundaiusa.com/") from ai_core.http to obtain valid Cloudflare session cookies via browser TLS impersonation before making the request.

Response shape: {"dealers": [{dealerCd, dealerNm, address1, city, state, zipCd, latitude, longitude, phone, dealerUrl, ...}]} (same camelCase schema as Hyundai). The entire dealers[] array is stored in one raw row.

This source is used as the sole (priority 1) dealer source in consolidation. When the allDealers endpoint returns a 403 from a server context, the inventory_search_dealers transformed asset (priority 2) provides a fallback — it lacks lat/lng but covers all dealers seen in inventory records.

Vehicle Catalog

The vehicle catalog returns the 8 current Genesis US models with modelName, modelYear, and vehicleSeries. It requires no parameters and is fetched as a single request.

URL: https://www.genesis.com/bin/api/v2/vehicles

Response shape: result[] — array of {modelName, modelYear, vehicleSeries}.

The vehicleSeries field is used as model_code in GenesisModelEntity — note this is a different namespace from SAPModelCd used in inventory. The two model sources are merged in the consolidated tier with vehicle_catalog at priority 1 (preferred) and inventory_search at priority 2.

BYO Configurator

Two endpoints are called per model slug and their results are stored together in a single raw row:

GET https://www.genesis.com/bin/api/v2/vehicle/byo?year=<year>&model=<slug>
GET https://www.genesis.com/bin/api/v2/vehicle/trims?year=<year>&model=<slug>

Required headers: Accept: application/json, Referer: https://www.genesis.com/

Model slug mapping

Model name	Slug
GV60	gv60
GV70	gv70
Electrified GV70	electrified-gv70
GV80	gv80
GV80 Coupe	gv80-coupe
G70	g70
G80	g80
G90	g90

BYO endpoint response shape (result)

{
  "modelName": "GV80",
  "modelYear": "2026",
  "seriesModelGroupCode": "V001",
  "trim": [...],
  "exteriorColors": [
    {"colorCode": "WHT", "colorName": "ALTA WHITE", "price": "0"},
    {"colorCode": "MAG", "colorName": "Makalu Gray Matte", "price": "1500"}
  ],
  "interiorColors": [...],
  "accessories": [...],
  "freights": [{"region": "all", "price": "1495"}]
}

Trims endpoint response shape (result)

{
  "modelName": "gv80",
  "modelYear": "2026",
  "trims": [
    {
      "trimName": "2.5T RWD",
      "features": [
        {
          "category": "POWERTRAIN",
          "featuresList": [
            {
              "featureDesc": "2.5L Inline 4 Turbo GDI (300 hp / 311 lb.-ft.)",
              "packages": [{"packageName": "STANDARD", "featureAvailability": "true"}]
            }
          ]
        }
      ]
    }
  ]
}

Feature categories in the trims endpoint: POWERTRAIN, ADVANCED SAFETY, EXTERIOR, COMFORT & CONVENIENCE, MULTIMEDIA & CONNECTIVITY.

Fetch strategy

fetch_vehicle_configurator fans out one pair of GET requests (byo + trims) per model slug using parallel_call (max_workers=4). Each raw row stores the combined {"byo": <byo_result>, "trims": <trims_result>, "model_slug": "<slug>"} dict for that model.

Features entity structure

extract_features_and_colors produces two row types stored together in genesis/us/transformed/vehicle_configurator_features:

Spec rows — one row per (series_code, trim_name, feature_desc), sourced from trims.trims[].features[].featuresList[]. model_code is the seriesModelGroupCode from the BYO result (e.g. V001).

Field	Source / Value
spec_category	features[].category (e.g. POWERTRAIN, ADVANCED SAFETY)
spec_name	featuresList[].featureDesc
spec_value	packages[0].featureAvailability — "true" or "false"
model_code	seriesModelGroupCode from BYO result
trim_name	trims[].trimName

Exterior color rows — one row per (series_code, model_year, color_code), sourced from byo.exteriorColors[].

Field	Source / Value
spec_category	"exterior_color"
spec_name	exteriorColors[].colorName
spec_value	Premium price string (e.g. "650", "1500") or "0" for no charge
model_code	seriesModelGroupCode from BYO result
trim_name	"" (empty for color rows)

Environment Variables

No additional environment variables beyond the standard platform variables are required for this OEM.

Asset Keys

Asset	Key
Inventory source	genesis/us/sources/inventory_search_inventory
Inventory raw	genesis/us/raw/inventory_search_inventory
Dealer source	genesis/us/sources/dealer_list_dealers
Dealer raw	genesis/us/raw/dealer_list_dealers
Catalog source	genesis/us/sources/vehicle_catalog_models
Catalog raw	genesis/us/raw/vehicle_catalog_models
Configurator source	genesis/us/sources/vehicle_configurator_configurator
Configurator raw	genesis/us/raw/vehicle_configurator_configurator
Transformed inventory	genesis/us/transformed/inventory_search_inventory
Transformed dealers (primary)	genesis/us/transformed/dealer_list_dealers
Transformed dealers (fallback)	genesis/us/transformed/inventory_search_dealers
Transformed models (catalog)	genesis/us/transformed/vehicle_catalog_models
Transformed models (inventory)	genesis/us/transformed/inventory_search_models
Transformed features	genesis/us/transformed/vehicle_configurator_features
Consolidated dealers	genesis/us/consolidated/dealers
Consolidated models	genesis/us/consolidated/models
Consolidated features	genesis/us/consolidated/features
Consolidated inventory	genesis/us/consolidated/inventory