From 671fdaf8b2d30111e11ecafcfdc36e57e61877ba Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Wed, 17 Feb 2016 17:24:57 -0500 Subject: [PATCH] Added documentation for the Cloud API --- doc/source/bindings.rst | 32 ++++ doc/source/cloudapi.yaml | 322 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 354 insertions(+) create mode 100644 doc/source/cloudapi.yaml diff --git a/doc/source/bindings.rst b/doc/source/bindings.rst index 745d6cf..bc5f59c 100755 --- a/doc/source/bindings.rst +++ b/doc/source/bindings.rst @@ -175,6 +175,38 @@ The source code is available here: https://github.com/netPark/node-openalpr +.. _cloud_api: + +Cloud API (Commercial) +======================= + +The OpenALPR Cloud API is a web-based service that analyzes images for license plates as well as vehicle information such as make, model, and color. +The Cloud API service is easy to integrate into your application via a web-based REST service. You send image data to the OpenALPR API, we process the data, +and return JSON data describing the license plate and vehicle. + +Check out the online demo: http://www.openalpr.com/demo-image.html + +Sign-Up +--------- + +When you're ready to get started, sign-up for an account at https://cloud.openalpr.com/ + +Once enrolled, you will automatically be assigned a free account that has a limited number of API credits per month. Each time you use the service, you use one or more +API credits. You may enter your credit card information and upgrade your plan to give you access to more credits per month. + +Integrate +---------- + +Because the OpenALPR Cloud API is REST-based, it works with any programming language on any operating system. You can make API calls using whatever method +you prefer. + +To make integration easier, the OpenALPR Cloud API also includes permissively licensed open source client libraries in a variety of languages. +The GitHub repo is available here: https://github.com/openalpr/cloudapi + +Check out the `REST API documentation `_ for more detailed information about the REST service. +This is generated from the `OpenALPR Cloud API Swagger definition `_ + + .. _alpr_web_service: Docker-Based Web Service (Commercial) diff --git a/doc/source/cloudapi.yaml b/doc/source/cloudapi.yaml new file mode 100644 index 0000000..97e0f69 --- /dev/null +++ b/doc/source/cloudapi.yaml @@ -0,0 +1,322 @@ +swagger: '2.0' + +info: + version: "1.0.1" + title: OpenALPR Cloud API +host: api.openalpr.com +basePath: /v1 +schemes: + - https +produces: + - application/json + +paths: + # Send an image to OpenALPR and get the analyzed results + /recognize: + post: + description: | + Send an image for OpenALPR to analyze and provide metadata back + consumes: + - "multipart/form-data" + produces: + - application/json + parameters: + - + name: secret_key + in: query + description: | + The secret key used to authenticate your account. You can view your + secret key by visiting + https://cloud.openalpr.com/ + required: true + type: string + - + name: tasks + in: query + description: | + Tasks to execute. You can choose to detect the license plate, + as well as additional metadata about the vehicle. Each additional + option costs an API credit. + required: true + type: array + items: + type: string + enum: [ "plate", "color", "make", "makemodel"] + - + name: image + in: formData + description: | + The image file that you wish to analyze + At least one value for image, image_bytes, or image_url must be provided + required: true + type: file + - + name: image_bytes + in: query + description: | + The image file that you wish to analyze encoded in base64 + At least one value for image, image_bytes, or image_url must be provided + required: false + type: string + - + name: image_url + in: query + description: | + A URL to an image that you wish to analyze + At least one value for image, image_bytes, or image_url must be provided + required: false + type: string + - + name: country + in: query + 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 + + You may use multiple datasets by using commas between the country + codes. For example, 'au,auwide' would analyze using both the + Australian plate styles. A full list of supported country codes + can be found here + https://github.com/openalpr/openalpr/tree/master/runtime_data/config + required: false + type: string + - + name: state + in: query + description: | + Corresponds to a US state or EU country code used by OpenALPR pattern + recognition. For example, using "md" matches US plates against the + Maryland plate patterns. Using "fr" matches European plates against + the French plate patterns. + required: false + type: string + - + name: return_image + in: query + description: | + If set to 1, the image you uploaded will be encoded in base64 and + sent back along with the response + required: false + type: integer + enum: [0, 1] + - + name: topn + in: query + description: | + The number of results you would like to be returned for plate + candidates and vehicle classifications + required: false + type: integer + minimum: 1 + maximum: 1000 + - + name: prewarp + in: query + description: | + Prewarp configuration is used to calibrate the analyses for the + angle of a particular camera. More information is available here + http://doc.openalpr.com/accuracy_improvements.html#calibration + required: false + type: string + + # Expected responses for this operation: + responses: + # Response code + 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: + total_processing_time: + type: number + description: Time spent processing all tasks (in milliseconds) + img_width: + type: integer + description: Width of the uploaded image in pixels + img_height: + type: integer + description: Height of the input image in pixels + credit_cost: + type: integer + description: The number of API credits that were used to process this image + credits_monthly_used: + type: integer + description: The number of API credits used this month + credits_monthly_total: + type: integer + description: The maximum number of API credits available this month according to your plan + makemodel: + type: array + description: Results from makemodel vehicle analysis task + items: + $ref: '#/definitions/classification' + make: + type: array + description: Results from make vehicle analysis task + items: + $ref: '#/definitions/classification' + color: + type: array + description: Results from color vehicle analysis task + items: + $ref: '#/definitions/classification' + plate: + $ref: '#/definitions/alpr_plate' + + + + + 400: + description: Parameter is invalid + schema: + properties: + error: + type: string + description: Text error message describing the invalid input + 401: + description: User not authorized or invalid secret_key + schema: + properties: + error: + type: string + description: Text error message describing the invalid input + + 402: + description: Monthly usage limit exceeded + schema: + properties: + error: + type: string + description: Text error message describing the invalid input + 403: + description: Temporary rate-limit exceeded + schema: + properties: + error: + type: string + description: Text error message describing the invalid input + +definitions: + classification: + type: object + properties: + confidence: + type: number + value: + type: string + + coordinate: + type: object + properties: + x: + type: integer + y: + type: integer + + region_of_interest: + type: object + properties: + x: + type: integer + y: + type: integer + width: + type: integer + height: + type: integer + + plate_candidate: + type: object + properties: + plate: + type: string + description: Plate number + confidence: + type: number + description: Confidence percentage that the plate number is correct + matches_template: + type: integer + description: Indicates whether the plate matched a regional text pattern + + plate_details: + type: object + properties: + plate: + type: string + description: Best plate number for this plate + matches_template: + type: integer + description: Indicates whether the plate matched a regional text pattern + requested_topn: + type: integer + description: The max number of results requested + processing_time_ms: + type: number + description: Number of milliseconds to process the license plate + confidence: + type: number + description: Confidence percentage that the plate number is correct + region: + type: string + description: Specified or detected region (e.g., tx for Texas) + region_confidence: + type: number + description: Confidence percentage that the plate region is correct + coordinates: + type: array + 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' + candidates: + type: array + description: All the top N candidates that could be the correct plate number + items: + $ref: '#/definitions/plate_candidate' + + alpr_plate: + description: Results from plate analysis task + type: object + properties: + results: + type: array + items: + $ref: '#/definitions/plate_details' + img_width: + type: integer + description: Width of the uploaded image in pixels + img_height: + type: integer + description: Height of the input image in pixels + regions_of_interest: + type: array + description: Describes the areas analyzed in the input image + items: + $ref: '#/definitions/region_of_interest' + epoch_time: + # This is actually an integer, but setting to number to avoid issues with overflow + type: number + description: Epoch time that the image was processed in milliseconds + version: + type: integer + description: API format version + data_type: + type: string + enum: ["alpr_results", "alpr_group", "heartbeat"] + description: Specifies the type of data in this response + processing_time_ms: + type: number + description: Number of milliseconds to process all license plates