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.

POST/easydogana/normalize

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 400 UNSUPPORTED_VERSION, a retired one with 410 VERSION_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

Request

POST
/easydogana/normalize
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"
}
POST/easydogana/normalize/batch

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 400 UNSUPPORTED_VERSION, a retired one with 410 VERSION_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 own status and result or error. The call returns HTTP 207, not 200.BatchNormalizationResponse
  • 400Invalid input value.ErrorDetail
  • 401Missing, malformed, expired or wrongly-scoped credentials.ErrorDetail
  • 403The token is valid but carries none of the required scopes.ErrorDetail
  • 422Request body failed schema validation (detail is a list of errors), or the payload could not be normalised (detail is a string).HTTPValidationError | ErrorDetail
  • 500Unexpected engine error.ErrorDetail

Request

POST
/easydogana/normalize/batch
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

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.

Was this page helpful?