swagger: "2.0"
schemes:
  - https
host: api.openalpr.com
basePath: /v3
info:
  contact:
    x-twitter: openalpr
  description: |
    The OpenALPR CarCheck API allows you to send images to the cloud for processing. 
    The image will be analyzed for license plates and vehicle make/models.  The results 
    are returned in JSON format
  title: OpenALPR CarCheck API
  version: 3.0.1
  x-apisguru-categories:
    - cloud
  x-logo:
    url: https://twitter.com/openalpr/profile_image?size=original
  x-origin:
    - format: swagger
      url: http://doc.openalpr.com/api/specs/cloudapi.yaml
      version: "2.0"
  x-providerName: openalpr.com
produces:
  - application/json
parameters:
  country:
    description: |
      Defines the training data used by OpenALPR.  "us" analyzes 
      North-American style plates.  "eu" analyzes European-style plates.

      This field is required if using the "plate" task
    in: query
    name: country
    required: true
    type: string
  is_cropped:
    default: 0
    description: |
      When providing a plate or vehicle that is already cropped,  
      this performs a recognition against the full crop and does not 
      attempt to localize the plate/vehicle
    enum:
      - 0
      - 1
    in: query
    name: is_cropped
    required: false
    type: integer
  recognize_vehicle:
    default: 0
    description: |
      If set to 1, the vehicle will also be recognized in the image
      This requires an additional credit per request
    enum:
      - 0
      - 1
    in: query
    name: recognize_vehicle
    required: false
    type: integer
  return_image:
    default: 0
    description: |
      If set to 1, the image you uploaded will be encoded in base64 and 
      sent back along with the response
    enum:
      - 0
      - 1
    in: query
    name: return_image
    required: false
    type: integer
  secret_key:
    description: |
      The secret key used to authenticate your account.  You can view your 
      secret key by visiting 
      https://cloud.openalpr.com/
    in: query
    name: secret_key
    required: true
    type: string
  topn:
    default: 10
    description: |
      The number of results you would like to be returned for plate 
      candidates and vehicle classifications
    in: query
    maximum: 1000
    minimum: 1
    name: topn
    required: false
    type: integer
responses:
  api_200:
    description: OK
    headers:
      X-RateLimit-Limit:
        description: Maximum number of requests allowed from your IP in a period
        type: integer
      X-Ratelimit-Remaining:
        description: Number of remaining requests allowed during this period
        type: integer
      X-Ratelimit-Reset:
        description: Epoch time when the next period begins
        type: integer
    schema:
      properties:
        credit_cost:
          description: The number of API credits that were used to process this image
          type: integer
        credits_monthly_total:
          description: The maximum number of API credits available this month according to your plan
          type: integer
        credits_monthly_used:
          description: The number of API credits used this month
          type: integer
        data_type:
          description: Specifies the type of data in this response
          enum:
            - alpr_results
            - alpr_group
            - heartbeat
          type: string
        epoch_time:
          description: Epoch time that the image was processed in milliseconds
          type: number
        img_height:
          description: Height of the input image in pixels
          type: integer
        img_width:
          description: Width of the uploaded image in pixels
          type: integer
        processing_time:
          properties:
            plates:
              description: Time spent performing license plate recognition (in milliseconds)
              type: number
            total:
              description: Time spent processing all tasks (in milliseconds)
              type: number
            vehicles:
              description: Time spent performing vehicle recognition (in milliseconds)
              type: number
          type: object
        regions_of_interest:
          description: Describes the areas analyzed in the input image
          items:
            $ref: "#/definitions/region_of_interest"
          type: array
        results:
          items:
            $ref: "#/definitions/plate_details"
          type: array
        vehicles:
          description: Describes all vehicles found in the input image
          items:
            $ref: "#/definitions/vehicles"
          type: array
        version:
          description: API format version
          type: integer
  api_400:
    description: Parameter is invalid
    schema:
      properties:
        error:
          description: Text error message describing the invalid input
          type: string
  api_401:
    description: User not authorized or invalid secret_key
    schema:
      properties:
        error:
          description: Text error message describing the invalid input
          type: string
  api_402:
    description: Monthly usage limit exceeded
    schema:
      properties:
        error:
          description: Text error message describing the invalid input
          type: string
  api_403:
    description: Temporary rate-limit exceeded
    schema:
      properties:
        error:
          description: Text error message describing the invalid input
          type: string
paths:
  /config:
    get:
      description: |
        Get a list of available results for plate and vehicle recognition
      operationId: getConfig
      produces:
        - application/json
      responses:
        "200":
          description: ok
          schema:
            properties:
              countries:
                items:
                  properties:
                    code:
                      example: us
                      type: string
                    name:
                      example: North America
                      type: string
                  type: object
                type: array
              vehicle_labels:
                properties:
                  bodytype:
                    items:
                      example: sedan-compact
                      type: string
                    type: array
                  color:
                    items:
                      example: blue
                      type: string
                    type: array
                  make:
                    items:
                      example: volvo
                      type: string
                    type: array
                  makemodel:
                    items:
                      example: volvo_v40
                      type: string
                    type: array
                  orientation:
                    items:
                      example: 45
                      type: string
                    type: array
                  year:
                    items:
                      example: 2000-2004
                      type: string
                    type: array
                type: object
  /recognize:
    post:
      consumes:
        - multipart/form-data
      description: |
        Send an image for OpenALPR to analyze and provide metadata back
        The image is sent as a file using a form data POST
      operationId: recognizeFile
      parameters:
        - description: |
            The image file that you wish to analyze
          in: formData
          name: image
          required: true
          type: file
        - $ref: "#/parameters/secret_key"
        - $ref: "#/parameters/recognize_vehicle"
        - $ref: "#/parameters/country"
        - $ref: "#/parameters/return_image"
        - $ref: "#/parameters/topn"
        - $ref: "#/parameters/is_cropped"
      produces:
        - application/json
      responses:
        "200":
          $ref: "#/responses/api_200"
        "400":
          $ref: "#/responses/api_400"
        "401":
          $ref: "#/responses/api_401"
        "402":
          $ref: "#/responses/api_402"
        "403":
          $ref: "#/responses/api_403"
  /recognize_bytes:
    post:
      consumes:
        - application/json
      description: |
        Send an image for OpenALPR to analyze and provide metadata back
        The image is sent as base64 encoded bytes.
      operationId: recognizeBytes
      parameters:
        - description: |
            The image file that you wish to analyze encoded in base64
          in: body
          name: image_bytes
          required: true
          schema:
            type: string
        - $ref: "#/parameters/secret_key"
        - $ref: "#/parameters/recognize_vehicle"
        - $ref: "#/parameters/country"
        - $ref: "#/parameters/return_image"
        - $ref: "#/parameters/topn"
      produces:
        - application/json
      responses:
        "200":
          $ref: "#/responses/api_200"
        "400":
          $ref: "#/responses/api_400"
        "401":
          $ref: "#/responses/api_401"
        "402":
          $ref: "#/responses/api_402"
        "403":
          $ref: "#/responses/api_403"
  /recognize_url:
    post:
      consumes:
        - application/json
      description: |
        Send an image for OpenALPR to analyze and provide metadata back
        The image is sent as a URL.  The OpenALPR service will download the image 
        and process it
      operationId: recognizeUrl
      parameters:
        - description: |
            A URL to an image that you wish to analyze
          in: query
          name: image_url
          required: true
          type: string
        - $ref: "#/parameters/secret_key"
        - $ref: "#/parameters/recognize_vehicle"
        - $ref: "#/parameters/country"
        - $ref: "#/parameters/return_image"
        - $ref: "#/parameters/topn"
      produces:
        - application/json
      responses:
        "200":
          $ref: "#/responses/api_200"
        "400":
          $ref: "#/responses/api_400"
        "401":
          $ref: "#/responses/api_401"
        "402":
          $ref: "#/responses/api_402"
        "403":
          $ref: "#/responses/api_403"
definitions:
  coordinate:
    properties:
      x:
        type: integer
      y:
        type: integer
    type: object
  plate_candidate:
    properties:
      confidence:
        description: Confidence percentage that the plate number is correct
        type: number
      matches_template:
        description: Indicates whether the plate matched a regional text pattern
        type: integer
      plate:
        description: Plate number
        type: string
    type: object
  plate_details:
    properties:
      candidates:
        description: All the top N candidates that could be the correct plate number
        items:
          $ref: "#/definitions/plate_candidate"
        type: array
      confidence:
        description: Confidence percentage that the plate number is correct
        type: number
      coordinates:
        description: |
          The X/Y coordinates of the license plate in the image
          Four coordinates are provided that form a polygon starting
          from the top-left and moving clockwise ending in the bottom left
        items:
          $ref: "#/definitions/coordinate"
        type: array
      matches_template:
        description: Indicates whether the plate matched a regional text pattern
        type: integer
      plate:
        description: Best plate number for this plate
        type: string
      processing_time_ms:
        description: Number of milliseconds to process the license plate
        type: number
      region:
        description: Specified or detected region (e.g., tx for Texas)
        type: string
      region_confidence:
        description: Confidence percentage that the plate region is correct
        type: number
      requested_topn:
        description: The max number of results requested
        type: integer
      vehicle:
        $ref: "#/definitions/vehicle_details"
      vehicle_region:
        $ref: "#/definitions/region_of_interest"
    type: object
  region_of_interest:
    properties:
      height:
        type: integer
      width:
        type: integer
      x:
        type: integer
      y:
        type: integer
    type: object
  vehicle_candidate:
    properties:
      confidence:
        description: confidence of value (percent)
        type: number
      name:
        description: name of value
        type: string
    type: object
  vehicle_details:
    properties:
      body_type:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
      color:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
      make:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
      make_model:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
      orientation:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
      year:
        items:
          $ref: "#/definitions/vehicle_candidate"
        type: array
    type: object
  vehicles:
    properties:
      details:
        $ref: "#/definitions/vehicle_details"
      height:
        type: integer
      width:
        type: integer
      x:
        type: integer
      y:
        type: integer
    type: object
