openapi: 3.0.3
info:
  version: 0.1.0
  title: Kemiex Market Insights API
  description: >
    An API to provide access to Kemiex Market Insigts data.


    ## Rate limits


    A rate limit of 100 quota units per minute is enforced. Exceeding this limit
    returns HTTP code 429. The table below lists the corresponding quota units
    consumed per api endpoint.


    | Endpoint | Quota units |

    | -------- | ----------- |

    | `/price-benchmarks` | 1 unit |
servers:
  - url: https://{environment}.kemiex.com/market-insights/v1
    variables:
      environment:
        default: api
        enum:
          - dev.api
          - stage.api
          - api
paths:
  /price-benchmarks:
    get:
      summary: Kemiex Price Benchmarks
      description: >-
        Retrieve weekly price points that include average, minimum, maximum, and
        own company submission values for the specified products and date range.

        Price Benchmark data is published every Wednesday.
      parameters:
        - name: products
          in: query
          required: true
          description: |
            A comma-separated list of product-region codes to query (e.g.,
            VB1-EU,VAL-USW) <br>

            ### Available products:

            | Code    | Product |
            | ------- | ------- |
            | BIO | Biotin (2%) |
            | DLM | Dl-Methionine (99%) |
            | LYH | L-Lysine Hcl (98%) |
            | LYS | L-Lysine Sulfate (70%) |
            | THR | L-Threonine |
            | TRP | L-Tryptophan |
            | VAL | L-Valine |
            | VTA | Vitamin A (1'000) |
            | V12 | Vitamin B12 (1% HPLC) |
            | VB1 | Vitamin B1 (Mono) |
            | VB2 | Vitamin B2 (80%) |
            | VB3 | Vitamin B3 |
            | VB5 | Vitamin B5 (Calcium Pantothenate) |
            | VB6 | Vitamin B6 Hcl |
            | VB9 | Vitamin B9 (>96%) |
            | VTC | Vitamin C (99% powder) |
            | VCP | Vitamin C phosphate 35% |
            | VTD | Vitamin D3 (500) |
            | VTE | Vitamin E (50% Feed) |
            | VTK | Vitamin K3 MNB |

            ### Available regions:

            | Code    | Region |
            | ------- | ------ |
            | CN | FOB China |
            | EU | FCA Europe |
            | USE | CFR US East |
            | USW | CFR US West |
          schema:
            type: string
            example: VB1-EU,VAL-USW
        - name: startDate
          in: query
          required: true
          description: The start date for the price points series
          schema:
            type: string
            format: date
            example: '2024-01-01'
      responses:
        '200':
          description: A list of weekly price points for the specified products
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        productCode:
                          type: string
                          description: The code of the product
                          example: VB1
                        productName:
                          type: string
                          description: The name of the product
                          example: Vitamin B1
                        regionCode:
                          type: string
                          example: USE
                        regionName:
                          type: string
                          example: CFR US East
                        week:
                          type: string
                          format: date
                          description: >-
                            The Thursday date of the week for the price point.
                            Even though data may be published on a different
                            date, we list it on a Thursday, representing the
                            corresponding week number according to ISO 8601.
                          example: '2024-01-04'
                        currency:
                          type: string
                          description: Currency of the price point
                          example: USD
                        unit:
                          type: string
                          description: Unit of measure of the price point
                          example: kg
                        average:
                          type: number
                          format: double
                          description: The average price for the week
                          example: 15.75
                        minimum:
                          type: number
                          format: double
                          description: The minimum price for the week
                          example: 14.5
                        maximum:
                          type: number
                          format: double
                          description: The maximum price for the week
                          example: 16.25
                        ownCompanySubmission:
                          type: number
                          format: double
                          description: The price submitted by own company for the week
                          example: 15
        '400':
          description: Invalid input parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Invalid startDate format. Expected YYYY-MM-DD.
        '404':
          description: No price data found for the specified criteria
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: >-
                      No price data found for the selected products and date
                      range.
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An unexpected error occurred.
components:
  schemas:
    PricePoint:
      type: object
      properties:
        productCode:
          type: string
          description: The code of the product
        productName:
          type: string
          description: The name of the product
        week:
          type: string
          format: date
          description: The ending date of the week for the price data
        average:
          type: number
          format: float
          description: The average price for the week
        minimum:
          type: number
          format: float
          description: The minimum price for the week
        maximum:
          type: number
          format: float
          description: The maximum price for the week
        ownCompanySubmission:
          type: number
          format: float
          description: The own company's submitted price for the week
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Api-Key
security:
  - ApiKeyAuth: []
