openapi: 3.0.0

info:
  description: This is an AI-powered API that extracts tyre specifications and car make/model from a picture of the full tyre. Currently supports only passenger car tyres
  version: 1.0.0
  title: TyreSnap–FullTyre API
  contact:
    name: API Support
    email: difapiteam@michelin.com
    url: 'https://developer.michelin.com/en/contact'
    
servers:
  - url: https://dev.api.michelin.com/tire-size-recognition/v1
    description: dev
    
security:
    - OAuth2Indus: [rft-tire-size-recognition]    
    
tags:
  - name: TyreSnapFullTyre
    description: Extracts tyre specifications and car make/model from a picture of the full tyre.
    
paths:
  /score:
    post:
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: mode
          in: query
          required: false
          description: This mode enables customized response
          schema:
            type: string
            enum:
              - ts
              - ts-debug
              - debug
            description: >
              * ts - Response from tyresnap Only (RFT tyre Recommender)
              * ts-debug - Response from tyresnap & elapsed_time_sec,  start_time, stop_time and status_code details
              * ts - Response from tyresnap, tyremotion and Orchestrator API
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                tyre_image:
                  type: string
                  format: binary
                unique_request_id:
                  type: string
                  format: uuid
                  minLength: 21
                  maxLength: 23
                requester_name:
                  type: string
        description: Image upload request body
        required: true
      responses:
        '200':
          description: Success response containing tyre specifications and car model extracted from image
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComboSuccessResponse'
              examples:
                Image quality check passed:
                  "$ref": "#/components/examples/tyre_recognition_pass"
                Image angle is not proper:
                  "$ref": "#/components/examples/tyre_recognition_fail_1"
                Image distance is not proper:
                  "$ref": "#/components/examples/tyre_recognition_fail_2"
                Image not clear or blurrd:
                  "$ref": "#/components/examples/tyre_recognition_fail_3"
                Poor Brightness::
                  "$ref": "#/components/examples/tyre_recognition_fail_4"
                High Brightness:
                  "$ref": "#/components/examples/tyre_recognition_fail_5"
                Invalid file type:
                  "$ref": "#/components/examples/tyre_recognition_fail_6"
                Default response:  
                  "$ref": "#/components/examples/tyre_recognition_fail_7"
                
                 
        '401':
          description: Unauthorised error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyErrorResponse'
              example: |-
                {
                    "fault": {
                        "faultstring": "Invalid ApiKey",
                        "detail": {
                            "errorcode": "oauth.v2.InvalidApiKey"
                        }
                    }
                }
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyErrorResponse'
              example: |-
                {
                    "fault": {
                        "faultstring": "Spike arrest violation.",
                        "detail": {
                            "errorcode": "policies.ratelimit.SpikeArrestViolation"
                        }
                    }
                }
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyErrorResponse'
              example: |-
                {
                   "fault": {
                      "faultstring": "The Service is temporarily unavailable", 
                      "detail": {
                           "errorcode": "messaging.adaptors.http.flow.ServiceUnavailable"
                       }
                    }
                }
        '504':
          description: >-
            Gateway timeout. A response was not available to send within the
            stipulated time limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyErrorResponse'
              example: |-
                {
                    "fault": {
                        "faultstring": "Gateway Timeout",
                        "detail": {
                            "errorcode": "messaging.adaptors.http.flow.GatewayTimeout"
                        }
                    }
                }
      tags:
        - TyreSnapFullTyre
      description: Extracts tyre specifications and car make/model from a picture of the full tyre.
      operationId: scorePOST
      summary: Extracts tyre specifications and car make/model from a picture of the full tyre.
    x-swagger-router-controller: TyreSnapFullTyre
    
components:
  parameters:
    ApiKey:
      name: apikey
      in: header
      schema:
        type: string
      required: true
  securitySchemes:
    OAuth2Indus:
      type: oauth2
      description: This is the OAuth2 security scheme for the Indus environment
      flows:
        clientCredentials:
          tokenUrl: >-
            https://indus.api.michelin.com/idp/v1/internal/oauth/token/accesstoken?grant_type=client_credentials
          scopes:
            rft-tyre-size-recognition: This scope grants access to the TyreSnap–FullTyre API
  schemas:
    tyreDimensionSchema:
      type: object
      properties:
        tyresize:
          type: string
        height:
          type: string
        width:
          type: string
        structure:
          type: string
        diameter:
          type: string
        load_index:
          type: string
        speed_index:
          type: string
        original_equipment_marking:
          type: string
        special_marking:
          type: object
          properties:
            run_flat:
              type: string
            xl:
              type: string
            m_plus_s:
              type: string
    ComboSuccessResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              format: int32
            message:
              type: string
        result:
          type: object
          properties:
            car_models_matches:
              type: integer
              format: int32
            car_models:
              type: array
              items:
                type: object
                properties:
                  tyre_details:
                    type: object
                    properties:
                      tyre_line:
                        type: string
                      tyre_brand:
                        type: string
                  brand:
                    type: string
                  model:
                    type: string
                  wheel_cover:
                    type: string
                  start_year:
                    type: string
                  end_year:
                    type: string
                  tyre_dimensions:
                    type: object
                    properties:
                      same_front_and_rear_dimension:
                        type: boolean
                      front:
                        type: object
                        schema: null
                        $ref: '#/components/schemas/tyreDimensionSchema'
                      rear:
                        type: object
                        schema: null
                        $ref: '#/components/schemas/tyreDimensionSchema'
    ProxyErrorResponse:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
            detail:
              type: object
              properties:
                errorcode:
                  type: string
                  
  examples:
    tyre_recognition_pass:
      summary: Image quality check passed
      description: Success response with tyre Specifications from image
      value:
          {
            "error": {
                 "code": 0,
                 "message": "Success"
            },
            "result": {
                 "car_models_matches": 1,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "205/60 R 16 92H",
                                  "height": "60",
                                  "width": "205",
                                  "diameter": "16",
                                  "load_index": "92",
                                  "speed_index": "H",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "R",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "205/60 R 16 92H",
                                 "height": "60",
                                 "width": "205",
                                 "diameter": "16",
                                 "load_index": "92",
                                 "speed_index": "H",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "R",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "REN",
                          "model": "GD SCENIC II",
                          "wheel_cover": "W",
                          "start_year": "2003",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }}
                  ]
              }
          }
        
    tyre_recognition_fail_1:
      summary: Image angle is not proper
      description: If the picture angle is not correct
      value:
          {
            "error": {
                 "code": 101,
                 "message": "The picture angle is not correct. Camera should face tyre properly."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }
    
    tyre_recognition_fail_2:
      summary: Image distance is not proper
      description: If the wheel distance is not correct
      value:
          {
            "error": {
                 "code": 102,
                 "message": "The wheel distance is not correct. Camera should face tyre properly."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }   
          
    tyre_recognition_fail_3:
      summary: Image not clear or blurrd
      description: If the image is blur
      value:
          {
            "error": {
                 "code": 103,
                 "message": "The picture blurry. Please click again."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }
          
    tyre_recognition_fail_4:
      summary: Poor Brightness
      description: If the image is with poor brightness
      value:
          {
            "error": {
                 "code": 104,
                 "message": "The picture is taken in darkness. Please click again with heigher brightness."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }      
    
    tyre_recognition_fail_5:
      summary: High Brightness
      description: If the image is with high brightness
      value:
          {
            "error": {
                 "code": 105,
                 "message": "The picture is taken with high brightness. Please click again."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }      
          
    tyre_recognition_fail_6:
      summary: Invalid file type
      description: If the attached file is invalid
      value:
          {
            "error": {
                 "code": 106,
                 "message": "Invalid attachment, Attach JPEG/PNG/JPG/BMP/WEBP Image."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }
          
    tyre_recognition_fail_7:
      summary: Default response
      description: Default response for invalid images.
      value:
          {
            "error": {
                 "code": 300,
                 "message": "Recognition Failed, Please try again."
            },
            "result": {
                 "car_models_matches": 0,
                 "car_models": [
                     {
                         "tyre_dimensions": {
                             "same_front_and_rear_dimension": true,
                             "front": {
                                  "tyresize": "",
                                  "height": "",
                                  "width": "",
                                  "diameter": "",
                                  "load_index": "",
                                  "speed_index": "",
                                  "special_marking": {
                                      "runflat": "",
                                      "xl": "",
                                      "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                              },
                            "rear": {
                                 "tyresize": "",
                                 "height": "",
                                 "width": "",
                                 "diameter": "",
                                 "load_index": "",
                                 "speed_index": "",
                                 "special_marking": {
                                     "runflat": "",
                                     "xl": "",
                                     "m_plus_s": ""
                                  },
                                  "structure": "",
                                  "original_equipment_marking": ""
                            }
                          },
                          "brand": "",
                          "model": "",
                          "wheel_cover": "",
                          "start_year": "",
                          "end_year": "",
                          "tyre_details": {
                          "tyre_line": "",
                          "tyre_brand": ""
                                      }
                      }
                  ]
              }
          }      
  