Skip to main content

BMW private UCP source

Catalog and authentication​

The private client is ai_bmw.sources.ucp_private. The public client is ai_public_api.bmw.ucp and uses https://prod.ucp.bmw.cloud. Private assets use the ucp_private source name, for example bmw/us/raw/ucp_private_models.

UcpPrivateRawComponent accepts these regional settings. The repository configures private UCP for the US market.

SettingUS configuration
api_base_urlhttps://author.m2m.ucp.bmw.cloud
data_sourcesprint-pre-soc
countryus
languageen
currencyUSD
model_year_window1
token_urlPROD OAuth endpoint listed below

The shared client preserves model codes verbatim. Without model_year_window, the component selects all models. The window applies only to country us, where the first two model-code characters encode the model year.

Credentials are read at fetch time. Each region specifies its credential environment-variable names:

SettingUS environment variableValue
api_key_envBMW_US_UCP_API_KEYPre-SOC API key
client_id_envBMW_US_UCP_CLIENT_IDBMW UCP OAuth client ID
client_secret_envBMW_US_UCP_CLIENT_SECRETBMW UCP OAuth client secret

The OAuth client secret and API key are separate credentials. Inject them into local processes or the BMW branch deployment's run containers using the secret manager. Keep credential values out of configuration files and source control.

The default token endpoint is https://emea.prod.alpha.sso.bmwgroup.com/auth/oauth2/realms/root/realms/alpha/access_token. The client posts form data with grant_type=client_credentials and scope machine2machine client_<client_id>. Author and Prod use PROD OAuth credentials. Release uses https://release.m2m.ucp-int.bmw.cloud and the corresponding token endpoint under https://emea.int.alpha.sso.bmwgroup.com with INT credentials.

Every UCP request sends both Authorization: Bearer <token> and x-api-key. A fetch shares one token across its workers and renews it before expiry. Token transport failures and HTTP 429 or any 5xx receive up to three retries; invalid credentials and malformed token responses fail the fetch. Tokens are not persisted. Credentials are excluded from recorded request data and logs. API and token requests use HTTPS without redirects.

Original endpoints​

UCP calls a localized description a phrase: the display text for a model, option or body style in one language, with the interval over which that wording applies. The phrases in a resource name and in a response body are that vendor term, not a description of the code.

The endpoint paths use these substitutions:

PlaceholderValue
{source}Configured catalog source; sprint-pre-soc for the US
{model}Original model code from the models response
{country}Configured country; us for the US
{language}Configured language; en for the US
{currency}Configured currency; USD for the US
Raw resourceGET path
models/vehicles/sources/{source}/brands/bmwCar/countries/{country}/models
primary_data/vehicles/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/primary-data
options/vehicles/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/options
model_phrases/localisations/original-phrases/sources/{source}/brands/bmwCar/countries/{country}/models/languages/{language}
option_phrases/localisations/original-phrases/sources/{source}/brands/bmwCar/countries/{country}/models/{model}/options/languages/{language}
prices/pricing/internal/original-prices/price-lists/{source}/brands/bmwCar/countries/{country}/models/{model}?currency={currency}

Model phrases are fetched once per configured country and language. The request has no model or effect-date filter. Each model has a phrases array containing the original descriptions and validFrom/validTo intervals. The raw response preserves every interval, including missing bounds and placeholder descriptions such as SALES_DESCR. A model absent from this response has no model-name entry in that capture.

The enumerator has no model filter and its complete response is retained. US per-model requests use an inclusive model-year window around the partition year: with model_year_window: 1, a 2026 partition includes model years 2025–2027. The year is 2000 plus the first two model-code characters. A wider window includes model years the BYO catalog has no configurator for, and rules for those years reference features the catalog cannot resolve. Invalid year prefixes fail enumeration. The model coverage check reports eligible and skipped counts and every skipped model code. Each eligible model produces four original endpoint requests. Missing configuration bounds leave the corresponding request dates null. The client still requests all four per-model resources.

Four concurrent workers use the shared ai_http retry handling, with three retries per request. Raw rows preserve the complete response body and the standard raw schema. _request_params records:

  • Request URL and resource.
  • Catalog source and country scope.
  • Country, language, and currency.
  • Capture date and applicable model codes.
  • Selected effect and order dates, when applicable.

The model coverage check requires exactly one data or expected-unavailable response per eligible request. It reports response counts by availability. For unavailable prices, it reports:

  • Model code.
  • HTTP status and UCP error code.
  • Reason for unavailability.

The blocking fetch_attempts check has a zero terminal-failure tolerance. Empty or inconsistent model enumeration and malformed response bodies fail validation.

Only these US original-prices responses are accepted as expected unavailability:

HTTP statusUCP errorCodeUCP errorMessageRecorded reason
404PRI_B_1015anyno_model_price
400PRI_B_1004starts with "Model not found"model_not_in_price_catalog

UCP also returns PRI_B_1004 for errors unrelated to a missing model; see Error responses.

These outcomes preserve the original error body. Their _request_params include:

  • availability: "unavailable".
  • http_status.
  • ucp_error_code.
  • unavailable_reason.

Successful data responses record availability: "available". An accepted unavailable response has a successful fetch outcome while retaining its actual HTTP status. It contains no price data. Other error responses use normal failure and retry handling. Authentication failures and exhausted retries fail the fetch.

Captured evidence​

Replay fixtures live under projects/ai_bmw/tests/data/ucp/. 1029-price-unavailable.json and 277P-price-unavailable.json capture the Author / sprint-pre-soc missing-price responses listed above. model-phrases-pre-soc.json is a complete Author / sprint-pre-soc response containing 1,175 model entries. Model 277P has two phrase intervals. The other UCP response fixtures are Author / sprint-sim captures. Credentials are supplied outside the payload. models.json contains 1,201 unfiltered models; models-filtered.json is a comparison response for 1029 and 277P. Model 277P contains:

  • 455 rules.
  • 248 options.
  • 11 packages.
  • 150 combination-price entries.

The historical 1029 primary response has 224 rule statements, including two intervals of 15803. byo-typelist.json contains 136 model identity mappings.

overridden-models.json and 277P-overridden-options.json are comparison fixtures. They contain no rule collection; the ingestion uses primary-data for rules and original endpoints for product data with validity intervals.

A local curl configuration can supply both authentication headers for pre-SOC requests. Keep it outside the repository and refresh the bearer token using the client-credentials endpoint before it expires.