Skip to main content

Hyundai Public API Sources

The ai_hyundai pipeline uses three public API endpoints — no authentication credentials are required. The BSI API endpoints require Origin and Referer headers; the dealer locator requires Referer only.

Endpoints​

Ingested​

SourceResourceMethodURL
inventory_searchinventoryPOSThttps://papp-bsi-api.hyundaiusa.com/inventory/item/v2/search
dealer_locatordealersGEThttps://www.hyundaiusa.com/var/hyundai/services/dealer.allDealers.service
vehicle_modelsmodelsPOSThttps://papp-bsi-api.hyundaiusa.com/inventory/vehicle-models/v1/search

Discovered, not currently ingested​

EndpointMethodURLWhat it provides
BYO model indexGEThttps://www.hyundaiusa.com/var/hyundai/services/byo.build.jsonAll BYO-eligible models with seriesModelGroupCode and starting price
BYO builder APIPOSThttps://papp-bsi-api.hyundaiusa.com/inventory/builder-api/v1/searchPer-model accessory catalog with individual prices; same color pricing as vehicle-models

See BYO Configurator Endpoints for details.

POST https://papp-bsi-api.hyundaiusa.com/inventory/item/v2/search

Required headers​

HeaderValue
Originhttps://www.hyundaiusa.com
Refererhttps://www.hyundaiusa.com/
Acceptapplication/json, text/plain, */*
Content-Typeapplication/json;charset=UTF-8

Request body​

{
  "zipCode": "10001",
  "distance": 5000,
  "page": 1,
  "pageSize": 100,
  "sort": {"attributeName": "distance", "order": "asc"},
  "atDealershipOnly": false,
  "availableOnline": false,
  "filterTag": null,
  "personalization": null
}

Response shape​

The API returns an envelope with data.total (integer) and data.items[].

{
  "data": {
    "total": 33285,
    "items": [
      {
        "vin": "KMHLM4DJ8TU208020",
        "dealerCode": "NY144",
        "dealerName": "Koeppel Hyundai",
        "dealerAddress": "34-54 44th Street",
        "dealerLatitude": 40.74,
        "dealerLongitude": -73.92,
        "model": "ELANTRA",
        "modelDisplayName": "ELANTRA",
        "modelYear": 2026,
        "trim": "SEL SPORT PREMIUM",
        "trimDisplayName": "SEL Sport Premium",
        "trimId": "K",
        "sapModelCode": "494K2F4S",
        "bsiModelCode": "494K2F4S",
        "inventoryStatusCode": "AA",
        "msrp": 26985.0,
        "dealerInternetPrice": 25985.0,
        "exteriorColor": "AMAZON GRAY",
        "exteriorColorCode": "A5G",
        "exteriorGenericColor": "gray",
        "interiorColor": "BLACK",
        "interiorColorCode": "NNB",
        "drivetrain": "FRONT WHEEL DRIVE",
        "drivetrainCode": "F",
        "drivetrainName": "FWD",
        "engine": "2.0L 4-CYL",
        "transmission": "AUTO",
        "transmissionCode": "2",
        "horsepower": 147,
        "cityMpg": 30.0,
        "highwayMpg": 40.0,
        "createDate": "2026-05-28 00:00:00",
        "plannedDeliveryDate": null,
        "optionCodes": ["C1", "CF", "CN"],
        "distanceFromOrigin": "4.1"
      }
    ]
  }
}

Field mapping​

Inventory fields (each items[] element):

API fieldCanonical fieldNotes
vinvinPrimary key
dealerCodedealer_idFK to dealers
modelYearmodel_yearInteger in API; coerced to string
modelmodel_codeUppercase model name, e.g. ELANTRA
trimIdtrim_codeSingle-letter or short code, e.g. K
trimtrim_nameDisplay name, e.g. SEL SPORT PREMIUM
exteriorColorCodeext_color_code
exteriorColorext_color_name
interiorColorCodeint_color_code
interiorColorint_color_name
drivetrainNamedrive_traine.g. FWD, AWD
engineengine_typee.g. 2.0L 4-CYL
transmissiontransmissione.g. AUTO
msrpmsrpFloat
inventoryStatusCodeinventory_statusSee status codes below
plannedDeliveryDateestimated_arrival_dateNull for on-lot vehicles

Dealer fields (extracted from the same items[] elements, deduplicated by dealerCode):

API fieldCanonical field
dealerCodedealer_id
dealerNamename
dealerAddressaddress
dealerLatitudelatitude
dealerLongitudelongitude

Model fields (extracted from unique (gerpModelCode, modelYear, trimId) tuples):

API fieldCanonical fieldNotes
gerpModelCodemodel_codeCross-source join key — matches powerTrain[].gerpModelCode in the vehicle-models endpoint
modelYearmodel_year
modelDisplayNamemodel_name
trimIdtrim_code
trimtrim_name
drivetrainNamedrive_train
engineengine_type
transmissiontransmission

Inventory status codes​

CodeMeaning
AAAvailable — physically on lot
DSIn transit to dealer
IRIn route
PAPort arrival

Pagination and coverage​

The API uses offset-based page numbers (page, pageSize). data.total drives the page count: ceil(total / pageSize) pages are fetched. With distance=5000 from zip 10001, the API returns results sorted by distance from New York and covers the full US fleet — approximately 33,300 vehicles. Page size is 100; paginated_post_raw_fetch_result runs up to 4 pages concurrently (max_workers=4). Each raw row stores the items[] array from one page (extracted from the response envelope by _extract_items_content).

Three extractors from one raw asset​

All three entity types — inventory, dealers, and models — are extracted from hyundai/us/raw/inventory_search_inventory 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

The dealer and model transforms deduplicate by dealerCode and (model, modelYear, trimId) respectively as they scan across pages.

allDealers Locator​

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

Required headers​

HeaderValue
Refererhttps://www.hyundaiusa.com/us/en/dealer-locator
Acceptapplication/json, text/plain, */*

Query parameters​

ParamValue
brandhyundai
modelall
langen

Response shape​

{
  "dealers": [
    {
      "dealerCd": "AK003",
      "dealerNm": "LITHIA HYUNDAI OF ANCHORAGE",
      "address1": "...",
      "city": "ANCHORAGE",
      "state": "AK",
      "zipCd": "99503",
      "latitude": 61.18,
      "longitude": -149.87,
      "phone": "...",
      "dealerUrl": "...",
      "isIoniqDealer": false,
      "isLocatorActive": true
    }
  ]
}

A single request returns all ~861 US Hyundai dealers with no geographic filtering. The dealer_locator raw asset stores the entire dealers[] array in one row.

Field mapping​

API fieldCanonical field
dealerCddealer_id
dealerNmname
address1address
citycity
statestate
zipCdzip_code
latitudelatitude
longitudelongitude
phonephone
dealerUrlurl

This source is used as the sole (priority 1) dealer source in consolidation — it provides richer metadata (phone, URL, type flags) than the inventory-embedded dealer records.

BSI Vehicle Models​

POST https://papp-bsi-api.hyundaiusa.com/inventory/vehicle-models/v1/search

Required headers​

Same as the inventory search: Origin, Referer, Accept, Content-Type.

Request body​

{"zipCode": "10001", "distance": 5000, "filterTag": null}

Response shape​

{
  "data": [
    {
      "modelGroupCode": "J001",
      "modelName": "PALISADE",
      "yearGroups": [
        {
          "year": 2026,
          "vehicleModel": {
            "seriesModelGroupCode": "J001",
            "modelYear": "2026",
            "modelName": "PALISADE",
            "minPrice": 39435.0,
            "maxPrice": 56560.0,
            "freights": [{"region": "all", "price": "1600"}],
            "exteriorColors": [
              {"colorCode": "A2B", "colorName": "Abyss Black", "price": null},
              {"colorCode": "YBM", "colorName": "Earthy Brass Matte", "price": "1000"}
            ],
            "compareSpecifications": [
              {
                "categoryName": "Safety/SmartSense",
                "specSubCategory": [
                  {
                    "subCategoryName": "SmartSense",
                    "specifications": [
                      {
                        "name": "Forward Collision-Avoidance Assist",
                        "values": [
                          {"trimId": "1", "value": "Standard"},
                          {"trimId": "4", "value": "Standard"}
                        ]
                      }
                    ]
                  }
                ]
              }
            ],
            "trim": [
              {
                "trimID": "1",
                "trimName": "SE",
                "minPrice": 39435.0,
                "maxPrice": 41435.0,
                "powerTrain": [
                  {
                    "modelCode": "J2412A65",
                    "driveTrain": "AWD",
                    "transmissionName": "Automatic",
                    "horsePower": "287",
                    "price": 41435.0,
                    "packages": [{"packageID": "P1", "packageName": "NO PACKAGE"}]
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

A single request returns all 20 current-MY models. The raw asset stores the data[] array in one row.

Two extractors from one raw asset​

vehicle_models/models feeds two transformed assets:

extract_models — one row per unique (gerpModelCode, modelYear, trimID) powertrain variant, flattened from data[].yearGroups[].vehicleModel.trim[].powerTrain[]. model_code is the powertrain-level gerpModelCode (e.g. PL1AAJ9AW8A5) — this matches the gerpModelCode field on BSI inventory items, enabling the cross-source FK join from consolidated inventory to consolidated models. The per-model freight destination charge (freights[0].price) is stored as freight_price.

Source pathCanonical fieldNotes
powerTrain[].gerpModelCodemodel_codeCross-source join key — matches gerpModelCode on inventory items
yearGroups[].yearmodel_year
modelNamemodel_name
trim[].trimIDtrim_codeCoerced to string
trim[].trimNametrim_name
powerTrain[].driveTraindrive_train
powerTrain[].transmissionNametransmission
powerTrain[].pricebase_msrp
freights[0].pricefreight_price

extract_features_and_colors — produces three row types stored together in hyundai/us/transformed/vehicle_models_features:

Spec rows — one row per (model_code, trimId, spec_name), sourced from compareSpecifications. model_code is the FWD powertrain's modelCode for the trim (falls back to the first powertrain when no FWD entry exists), so the FK join to the models consolidated entity resolves correctly.

FieldSource / Value
spec_categorycompareSpecifications[].categoryName (e.g. Safety/SmartSense, Powertrain & Handling)
spec_subcategoryspecSubCategory[].subCategoryName
spec_namespecifications[].name
spec_value"Standard", "Available", "Not Available", or numeric string
model_codeFWD powertrain gerpModelCode for the trim
trim_codetrimId from compareSpecifications values

bsiTrimFeatures rows — one row per (model_code, trimId, feature_name), sourced from the bsiTrimFeatures dict on each trim object. This is a curated set of marketing-facing features grouped into categories by Hyundai's BSI system. spec_value is always "true" (presence indicates availability on that trim).

FieldSource / Value
spec_categorybsiTrimFeatures key (e.g. comfort, connectivity, drivingAssistance, infotainment, parkingConvenience)
spec_subcategory"bsiTrimFeatures"
spec_namefeature name string from the category list
spec_value"true" (always — presence implies availability)
model_codeFWD powertrain gerpModelCode for the trim
trim_codetrimID from the trim object

Exterior color rows — one row per (seriesModelGroupCode, model_year, colorCode).

FieldSource / Value
spec_category"exterior_color"
spec_subcategory"pricing"
spec_nameexteriorColors[].colorName
spec_valuePremium price string ("500", "1000") or "0" for no charge
model_codeseriesModelGroupCode (e.g. "8001") — no FK match to models

Package pricing note​

Hyundai does not sell priced option packages at the trim level. The packages array on each powertrain object contains only seat configuration choices (e.g. "Captain's Chair Option" vs "Bench Seat Option") with totalPackagePrice=0. These are mutually exclusive seating selections, not paid add-ons.

BYO Configurator Endpoints​

These two endpoints power the Build Your Own configurator on the Hyundai website. They are not currently wired into the Dagster pipeline but are documented here for future ingestion or reference.

BYO Model Index​

GET https://www.hyundaiusa.com/var/hyundai/services/byo.build.json

No authentication required. Returns a lightweight manifest of all BYO-eligible models — one entry per (modelYear, seriesModelGroupCode) — with starting price, body style, and the trim/powertrain/color shortIds used by the configurator UI.

The 17 current 2026 BYO-eligible models, with their seriesModelGroupCode:

ModelCodeStarting price
VENUE3001$20,550
KONAQ001$25,500
TUCSON8001$29,450
TUCSON Hybrid8006$32,450
TUCSON Plug-in Hybrid8005$40,325
SANTA CRUZ9001$29,750
IONIQ 55004$35,000
SANTA FE6001$35,050
SANTA FE Hybrid6006$36,400
PALISADEJ001$39,435
PALISADE HybridJ006$44,160
IONIQ 97004$58,955
ELANTRA4001$22,625
ELANTRA Hybrid4006$25,450
ELANTRA N4008$35,100
SONATA2001$27,450
SONATA Hybrid2006$29,200

BYO Builder API​

POST https://papp-bsi-api.hyundaiusa.com/inventory/builder-api/v1/search

Required headers​

Same as the inventory search: Origin, Referer, Accept, Content-Type.

Request body​

{"seriesModelGroupCode": "J001", "modelYear": 2026, "zipCode": "10001", "radiusDistance": 100}

One request per model code. The zipCode / radiusDistance parameters control which dealers are factored into availability but do not affect the accessory or color catalog.

Response shape (relevant fields)​

{
  "vehicleModel": {
    "seriesModelGroupCode": "J001",
    "modelYear": "2026",
    "modelName": "PALISADE",
    "trim": [...],
    "exteriorColors": [
      {"colorCode": "A2B", "colorName": "Abyss Black", "price": null},
      {"colorCode": "YBM", "colorName": "Earthy Brass Matte", "price": "1000"}
    ],
    "accessories": [
      {"accessoryCode": "UC", "accessoryName": "100W Charging Cable", "price": "50", "accessoryType": "internal"},
      {"accessoryCode": "FL", "accessoryName": "All-season fitted liners", "price": "280", "accessoryType": "internal"},
      {"accessoryCode": "CV", "accessoryName": "Cargo screen", "price": "205", "accessoryType": "internal"}
    ]
  }
}

The accessories array contains ~29 items per model with individual MSRP prices. accessoryType is either "internal" (OEM-sourced, in the Hyundai catalog) or "external" (dealer-installed). This is the only source of dealer-installable accessory pricing in the Hyundai public API.

The exteriorColors[].price field is identical to what vehicle-models/v1/search returns — no new color pricing data from this endpoint.

Difference from vehicle-models/v1/search​

Datavehicle-modelsbuilder-api
Trim + powertrain pricing✅✅
compareSpecifications (feature availability)✅❌
bsiTrimFeatures (marketing features)✅❌
Exterior color pricing✅✅ (identical)
Accessories with prices (~29 items)❌ (empty array)✅
Freight charge✅❌

To ingest accessory pricing, a new raw source sweeping all 17 model codes via builder-api/v1/search would be needed. No additional infrastructure changes are required — the same BSI auth headers apply.

Data Relationships​

inventory ──dealer_id──────────→ dealers (consolidated)
inventory ──(model_code, model_year)──→ models (consolidated)
features  ──(model_code, model_year)──→ models (consolidated)  [spec rows only]

The consolidated tier resolves both inventory FKs: dealer_id → dealer_id and (model_code, model_year) → model_id. Features color rows use seriesModelGroupCode as model_code, which does not match the powertrain-level model codes, so the FK join produces no match for color rows — this is expected.

Environment Variables​

No Hyundai-specific environment variables are required beyond the standard platform variables (ICEBERG_CATALOG_URI, ICEBERG_WAREHOUSE, RAW_STORAGE_URI).

Asset Keys​

AssetKey
Inventory sourcehyundai/us/sources/inventory_search_inventory
Inventory rawhyundai/us/raw/inventory_search_inventory
Dealer sourcehyundai/us/sources/dealer_locator_dealers
Dealer rawhyundai/us/raw/dealer_locator_dealers
Vehicle models sourcehyundai/us/sources/vehicle_models_models
Vehicle models rawhyundai/us/raw/vehicle_models_models
Transformed inventoryhyundai/us/transformed/inventory_search_inventory
Transformed dealershyundai/us/transformed/dealer_locator_dealers
Transformed modelshyundai/us/transformed/vehicle_models_models
Transformed featureshyundai/us/transformed/vehicle_models_features
Consolidated dealershyundai/us/consolidated/dealers
Consolidated modelshyundai/us/consolidated/models
Consolidated featureshyundai/us/consolidated/features
Consolidated inventoryhyundai/us/consolidated/inventory