Normalization
Normalize raw product data from shops and marketplaces into clean text bundles that the classifier understands. Use it when you want to inspect or store the normalized data before you classify.
Normalize a product payload
Normalize a single product payload.
Accepts MarketRock Product or Generic Product payloads. Returns normalized text bundle and genericity detection.
Args: request: Normalization request with product payload
Returns: NormalizationResponse with request_id and normalized entity
Raises: HTTPException 422: If normalization fails HTTPException 400: If payload is invalid HTTPException 500: If unexpected error occurs
Required scope: ai-engine:easydogana:normalize:read
Parameters
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Allowed values:
2026-10-23. Default:2026-10-23.
Request body NormalizationRequest
- Name
payload- Type
- MarketRockProduct | GenericProduct
- required
- Description
Product payload (MarketRock Product or Generic)
- Name
request_id- Type
- string · nullable
- Description
Optional request ID (generated if not provided)
Responses
200Successful ResponseNormalizationResponse400Invalid input value.ErrorDetail401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail422Request body failed schema validation (detailis a list of errors), or the payload could not be normalised (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Request
Loading...
Response 200
{
"entity": {
"identifiers": {
"sku": "TS-001"
},
"is_generic": false,
"quality_score": 85,
"questions_for_operator": [],
"text_bundle": "[Apparel] Cotton T-shirt, crew neck: Short-sleeve crew-neck T-shirt, 100% cotton, jersey knit. (attrs: material: cotton, colour: white) [sku: TS-001]"
},
"request_id": "550e8400-e29b-41d4-a716-446655440002"
}Normalize up to 100 product payloads
Normalize multiple product payloads.
Processes 1-100 payloads per request. Returns HTTP 207 Multi-Status with per-item results. Set concurrency: true in the request body to process items concurrently.
Args: request: Batch normalization request with payloads array
Returns: BatchNormalizationResponse with request_id and per-item results
Raises: HTTPException 500: If unexpected error occurs
Required scope: ai-engine:easydogana:normalize:read
Parameters
- Name
ParceLabs-Version- Type
- string
- Description
API version as a date (
YYYY-MM-DD). Omit it to get the oldest supported version; it never moves to a newer one on its own. An unknown value is answered with 400UNSUPPORTED_VERSION, a retired one with 410VERSION_RETIRED. Every response echoes the resolved version in the same header.Allowed values:
2026-10-23. Default:2026-10-23.
Request body BatchNormalizationRequest
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Default:
false.
- Name
payloads- Type
- array of MarketRockProduct | GenericProduct
- required
- Description
Array of product payloads (1-100 items)
items ≥ 1, items ≤ 100.
- Name
request_id- Type
- string · nullable
- Description
Optional request ID (generated if not provided)
Responses
207Multi-Status: the batch ran; each item carries its ownstatusand result or error. The call returns HTTP 207, not 200.BatchNormalizationResponse400Invalid input value.ErrorDetail401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail403The token is valid but carries none of the required scopes.ErrorDetail422Request body failed schema validation (detailis a list of errors), or the payload could not be normalised (detailis a string).HTTPValidationError | ErrorDetail500Unexpected engine error.ErrorDetail
Request
Loading...
Response 207
{
"request_id": "550e8400-e29b-41d4-a716-446655440003",
"results": [
{
"entity": {
"identifiers": {
"sku": "TS-001"
},
"is_generic": false,
"quality_score": 85,
"questions_for_operator": [],
"text_bundle": "[Apparel] Cotton T-shirt, crew neck: Short-sleeve crew-neck T-shirt, 100% cotton, jersey knit. (attrs: material: cotton, colour: white) [sku: TS-001]"
},
"index": 0,
"processing_ms": 12.5,
"status": "success"
},
{
"error": "Failed to normalize product: Field 'description' is required",
"index": 1,
"processing_ms": 2.1,
"status": "error"
}
]
}Models
Objects used by the requests and responses on this page.
NormalizationRequest
Request for single product normalization.
- Name
payload- Type
- MarketRockProduct | GenericProduct
- required
- Description
Product payload (MarketRock Product or Generic)
- Name
request_id- Type
- string · nullable
- Description
Optional request ID (generated if not provided)
MarketRockProduct
MarketRock Product payload model (payload.json structure).
- Name
long_description- Type
- string
- required
- Description
Extended product description
- Name
payload_type- Type
- "product"
- required
- Description
Payload type discriminator for MarketRock Product
- Name
product_category- Type
- string
- required
- Description
Product category
- Name
product_id- Type
- string
- required
- Description
Unique product identifier
- Name
specs- Type
- map of string
- Description
Product specifications
- Name
title- Type
- string
- required
- Description
Product title
GenericProduct
Generic Product payload model (standard contract).
- Name
attributes- Type
- map of string
- Description
Product attributes
- Name
category- Type
- string
- required
- Description
Product category
- Name
description- Type
- string
- required
- Description
Product description
- Name
identifiers- Type
- map of string
- Description
Product identifiers (SKU, EAN, etc.)
- Name
payload_type- Type
- "generic"
- required
- Description
Payload type discriminator for Generic Product
- Name
title- Type
- string
- required
- Description
Product title
NormalizationResponse
Response for single product normalization.
- Name
entity- Type
- NormalizedEntity
- required
- Description
Normalized product entity
- Name
request_id- Type
- string
- required
- Description
Unique request ID for correlation
NormalizedEntity
Normalized product entity with text bundle and genericity detection.
- Name
identifiers- Type
- map of string
- Description
Product identifiers (SKU, EAN, etc.)
- Name
is_generic- Type
- boolean
- required
- Description
True if product is too generic for accurate classification
- Name
quality_score- Type
- integer
- required
- Description
Quality score 0-100
≥ 0, ≤ 100.
- Name
questions_for_operator- Type
- array of string
- Description
Questions to improve data quality
- Name
text_bundle- Type
- string
- required
- Description
Searchable text bundle in sectioned format
ErrorDetail
Body of every error returned through FastAPI's `HTTPException`.
- Name
detail- Type
- string
- required
- Description
Human-readable reason. Not a stable machine code.
HTTPValidationError
- Name
detail- Type
- array of ValidationError
- Description
ValidationError
- Name
ctx- Type
- object
- Description
- Name
input- Type
- any
- Description
- Name
loc- Type
- array of string | integer
- required
- Description
- Name
msg- Type
- string
- required
- Description
- Name
type- Type
- string
- required
- Description
BatchNormalizationRequest
Request for batch product normalization.
- Name
concurrency- Type
- boolean
- Description
Enable concurrent processing (default: sequential)
Default:
false.
- Name
payloads- Type
- array of MarketRockProduct | GenericProduct
- required
- Description
Array of product payloads (1-100 items)
items ≥ 1, items ≤ 100.
- Name
request_id- Type
- string · nullable
- Description
Optional request ID (generated if not provided)
BatchNormalizationResponse
Response for batch normalization (HTTP 207 Multi-Status).
- Name
request_id- Type
- string
- required
- Description
Unique request ID for correlation
- Name
results- Type
- array of BatchResultItem
- required
- Description
Per-item results
BatchResultItem
Result for one item in batch normalization.
- Name
entity- Type
- NormalizedEntity · nullable
- Description
Normalized entity if successful
- Name
error- Type
- string · nullable
- Description
Error message if failed
- Name
index- Type
- integer
- required
- Description
Index in original request array
- Name
processing_ms- Type
- number
- required
- Description
Processing time in milliseconds
- Name
status- Type
- string
- required
- Description
Processing status
Allowed values:
success,error.