Optical Character Recognition - Huawei...Optical Character Recognition (OCR) allows you to detect...

Optical Character Recognition

API Reference

Issue 01

Date 2020-11-25

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2020. All rights reserved.

No part of this document may be reproduced or transmitted in any form or by any means without priorwritten consent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei andthe customer. All or part of the products, services and features described in this document may not bewithin the purchase scope or the usage scope. Unless otherwise specified in the contract, all statements,information, and recommendations in this document are provided "AS IS" without warranties, guaranteesor representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Huawei Technologies Co., Ltd.Address: Huawei Industrial Base

Bantian, LonggangShenzhen 518129People's Republic of China

Website: https://www.huawei.com

Email: [email protected]

Issue 01 (2020-11-25) Copyright © Huawei Technologies Co., Ltd. i

https://www.huawei.com

mailto:[email protected]

Contents

1 Before You Start....................................................................................................................... 11.1 Overview.................................................................................................................................................................................... 11.2 API Calling..................................................................................................................................................................................11.3 Endpoints....................................................................................................................................................................................11.4 Constraints................................................................................................................................................................................. 21.5 Concepts..................................................................................................................................................................................... 2

2 API Overview............................................................................................................................ 4

3 Calling APIs............................................................................................................................... 63.1 Applying for a Service............................................................................................................................................................ 63.2 Making an API Request......................................................................................................................................................... 63.3 Authentication....................................................................................................................................................................... 113.4 Response.................................................................................................................................................................................. 12

4 APIs........................................................................................................................................... 154.1 Web Image OCR.................................................................................................................................................................... 154.2 Passport OCR.......................................................................................................................................................................... 204.3 Thailand ID Card OCR......................................................................................................................................................... 264.4 Myanmar ID Card OCR....................................................................................................................................................... 334.5 Myanmar Driving License OCR........................................................................................................................................ 404.6 Chile ID Card OCR.................................................................................................................................................................45

5 Appendix..................................................................................................................................495.1 Status Codes........................................................................................................................................................................... 495.2 Error Codes.............................................................................................................................................................................. 535.3 Obtaining a Project ID.........................................................................................................................................................595.4 Obtaining an Account ID....................................................................................................................................................605.5 Configuring Access Permissions of OBS........................................................................................................................ 61

A Change History...................................................................................................................... 63

Optical Character RecognitionAPI Reference Contents

Issue 01 (2020-11-25) Copyright © Huawei Technologies Co., Ltd. ii

1 Before You Start

1.1 OverviewOptical Character Recognition (OCR) allows you to detect and recognize printedcharacters in images and convert the characters into editable text.

OCR provides services through open Application Programming Interfaces (APIs).You can obtain the inference result by accessing and calling APIs in real time. Ithelps you collect key data automatically and build an intelligent business system,thereby improving service efficiency.

You can perform related operations based on the API description, syntax,parameter description, and examples provided in this document. For example, youcan call the API for recognizing characters in general text, cards, or receipts. APIsvary depending on regions. For details, see Endpoints. For details about alloperations supported by APIs, see API Overview.

If you intend to access OCR through an API, get familiar with OCR concepts. Fordetails, see the Service Overview.

OCR also provides software development kits (SDKs) for multiple programminglanguages. For details about how to use SDKs, see SDK Reference.

1.2 API CallingOCR provides Representational State Transfer (REST) APIs, allowing you to callAPIs using HTTPS. For details about API calling, see Calling APIs.

OCR also provides software development kits (SDKs) for multiple programminglanguages. For details about how to use SDKs, see SDK Reference.

1.3 EndpointsAn endpoint is the request address for calling an API. Endpoints vary depending onservices and regions. For the endpoints of all services, see Regions and Endpoints.

Optical Character RecognitionAPI Reference 1 Before You Start

Issue 01 (2020-11-25) Copyright © Huawei Technologies Co., Ltd. 1

https://support.huaweicloud.com/intl/en-us/productdesc-ocr/ocr_01_0002.html

https://support.huaweicloud.com/intl/en-us/sdkreference-ocr/ocr_04_0016.html

https://support.huaweicloud.com/intl/en-us/sdkreference-ocr/ocr_04_0016.html

https://developer.huaweicloud.com/intl/en-us/endpoint?OCR

Table 1-1 lists the endpoints of OCR. Select an endpoint based on your servicerequirements.

Table 1-1 OCR endpoints

Region

EndpointRegion

Endpoint Service

AP-HongKong

ap-southeast-1

ocr.ap-southeast-1.myhuaweicloud.com

Passport OCR, Myanmar ID Card OCR,and Myanmar Driving License OCR

AP-Bangkok

ap-southeast-2

ocr.ap-southeast-2.myhuaweicloud.com

Thailand ID Card OCR, Passport OCR,and Web Image OCR

LA-Santiago

la-south-2

ocr.la-south-2.myhuaweicloud.com

Chile ID Card OCR

1.4 ConstraintsFor details, see the API description and Constraints.

1.5 Concepts● Account

An account is created upon successful registration with HUAWEI CLOUD. Theaccount has full access permissions for all of its cloud services and resources.It can be used to reset user passwords and grant user permissions. Theaccount is a payment entity. For security purposes, do not directly use theaccount to perform routine management. Instead, create IAM users and grantthem permissions for routine management.

● UserA user is created in IAM using an account, for access to cloud services. Eachuser has their own identity credentials (password and access keys).An IAM user can view the account ID and user ID on the My Credentialspage of the console. The account name, username, and password will berequired for API authentication.

● RegionRegions are divided based on geographical location and network latency.Public services, such as Elastic Cloud Server (ECS), Elastic Volume Service(EVS), Object Storage Service (OBS), Virtual Private Cloud (VPC), Elastic IP(EIP), and Image Management Service (IMS), are accessible within the sameregion. Regions are classified as universal regions and dedicated regions. Auniversal region provides universal cloud services for common tenants. Adedicated region provides specific services for specific tenants.




https://console-intl.huaweicloud.com/iam/?locale=en-us#/myCredential

● AZAn AZ contains one or more physical data centers. It has independent cooling,fire extinguishing, moisture-proof, and electricity facilities. Within an AZ,computing, network, storage, and other resources are logically divided intomultiple clusters. AZs within a region are interconnected using high-speedoptical fibers to allow you to build cross-AZ high-availability systems.

● ProjectProjects group and isolate resources (including compute, storage, and networkresources) across physical regions. A default project is provided for eachHUAWEI CLOUD region, and subprojects can be created under each defaultproject. Users can be granted permissions to access all resources in a specificproject. For more refined access control, create subprojects under a projectand purchase resources in the subprojects. Users can then be assignedpermissions to access specific resources in the subprojects.

Figure 1-1 Project isolation model



2 API Overview

You can perform the operations described in Table 2-1 with OCR APIs.

Table 2-1 API description

API Description DeploymentRegion

PassportOCR

Passport OCR recognizes the text on the firstpage of a passport and returns the structuredinformation in JSON format.

AP-HongKong (ap-southeast-1)AP-Bangkok(ap-southeast-2)

Web ImageOCR

Web Image OCR recognizes characters in a webimage and returns the structured result in JSONformat.

AP-Bangkok(ap-southeast-2)

Thailand IDCard OCR

Thailand ID Card OCR recognizes the text on aThailand-issued national registration card.

AP-Bangkok(ap-southeast-2)

Myanmar IDCard OCR

Myanmar ID Card OCR recognizes the text on aMyanmar-issued national registration card.

AP-HongKong (ap-southeast-1)

MyanmarDrivingLicense OCR

Myanmar Driving License OCR recognizescharacters on a Myanmar-issued driver's licenseand returns the structured result in JSON format.

AP-HongKong (ap-southeast-1)

Optical Character RecognitionAPI Reference 2 API Overview


API Description DeploymentRegion

Chile IDCard OCR

Chile ID Card OCR recognizes the text in a ChileID card image and returns the recognition resultin JSON format.

LA-Santiago-(la-south-2)

Optical Character RecognitionAPI Reference 2 API Overview


3 Calling APIs

3.1 Applying for a ServiceBefore using OCR, you must apply for it. The following is the procedure forapplying for OCR.

NO TE

● Before applying for OCR, you must register a HUAWEI CLOUD account.

● Before using OCR for the first time, subscribe to it. You only need to subscribe to OCRonce.

● When using OCR for the first time, you need to configure the OBS access permissiononce. For details, see Configuring Access Permissions of OBS.

1. Go to the OCR homepage and click Try Now to go to the OCR console. Youneed to have an account for logging in to the OCR console.

2. Select a region where OCR is deployed.3. On the Overview page, locate the target service and click Subscribe in the

Operation column of the service.4. After the service is successfully subscribed to, check that the status is

Subscribed.

3.2 Making an API RequestThis section describes the structure of a REST API, and uses the IAM API forobtaining a user token as an example to demonstrate how to call an API. Theobtained token can then be used to authenticate the calling of other APIs.

Request URIA request URI is in the following format:

{URI-scheme} :// {endpoint} / {resource-path} ? {query-string}

Although a request URI is included in the request header, most programminglanguages and frameworks require the request URI to be transmitted separately.

Optical Character RecognitionAPI Reference 3 Calling APIs


https://www.huaweicloud.com/intl/en-us/product/ocr.html

https://support.huaweicloud.com/intl/en-us/api-iam/iam_30_0001.html

Table 3-1 URI parameter description

Parameter Description

URI-scheme Protocol used to transmit requests. All APIs use HTTPS.

endpoint Domain name or IP address of the server bearing the RESTservice. The endpoint varies between services in differentregions. It can be obtained from Regions and Endpoints.

resource-path Access path of an API for performing a specified operation.Obtain the path from the URI of an API. For example, theresource-path of the API used to obtain a user token is /v3/auth/tokens.

query-string Query parameter, which is optional. Ensure that a questionmark (?) is included before each query parameter that is in theformat of "Parameter name=Parameter value". For example,limit=10 indicates that a maximum of 10 data records will bedisplayed.

For example, to obtain an IAM token in the AP-Hong Kong region, obtain theendpoint of IAM (iam.ap-southeast-1.myhuaweicloud.com) for this region andthe resource-path (/v3/auth/tokens) in the URI of the API used to obtain a usertoken. Then, construct the URI as follows:

https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens

Figure 3-1 Example URI

NO TE

To simplify the URI display in this document, each API is provided only with a resource-path and a request method. The URI-scheme of all APIs is HTTPS, and the endpoints of allAPIs in the same region are identical.

Request MethodsThe HTTP protocol defines the following request methods that can be used tosend a request to the server:



https://developer.huaweicloud.com/intl/en-us/endpoint?OCR



Table 3-2 HTTP-defined request methods

Method Description

GET Requests the server to return specified resources.

PUT Requests the server to update specified resources.

POST Requests the server to add resources or perform specialoperations.

DELETE Requests the server to delete specified resources, forexample, an object.

HEAD Same as GET except that the server must return only theresponse header.

PATCH Requests the server to update partial content of a specifiedresource.If the resource does not exist, a new resource will becreated.

For example, in the case of the API used to obtain a user token, the requestmethod is POST. The request is as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json X-Auth-Token: ABCDEFJ....

Request HeaderYou can also add additional header fields to a request, such as the fields requiredby a specified URI or HTTP method. For example, to request for the authenticationinformation, add Content-Type, which specifies the request body type.

Common request header fields are as follows:

Table 3-3 Common request header fields

Field Description Mandatory Example

Content-Type

Specifies the MIMEtype of the requestbody.

Yes application/json

Content-Length

Specifies the length ofthe request body. Theunit is byte.

This field ismandatory forPOST and PUTrequests, butmust be leftblank for GETrequests.

3495




Field Description Mandatory Example

X-Project-ID

Specifies the projectID. This field is used toobtain the token foreach project.This field is mandatoryfor the request from aDeC or multi-projectuser.

No e9993fc787d94b6c886cbaa340f9c0f4

X-Auth-Token

Specifies the usertoken.

This field ismandatory fortoken-basedauthentication.

-

X-Sdk-Date

Time when therequest is sent. Thetime is inYYYYMMDD'T'HHMMSS'Z' format.The value is thecurrent GreenwichMean Time (GMT) ofthe system.

This field ismandatory forAK/SK-basedauthentication.

20150907T101459Z

Authorization

Specifies signatureauthenticationinformation.The value can beobtained from therequest signing result.


SDK-HMAC-SHA256Credential=ZIRRKMTWPTQFQI1WKNKB/20150907//ec2/sdk_request,SignedHeaders=content-type;host;x-sdk-date,Signature=55741b610f3c9fa3ae40b5a8021ebf7ebc2a28a603fc62d25cb3bfe6608e1994

Host Specifies the serverdomain name andport number of theresource beingrequested. The valuecan be obtained fromthe URL of a serviceAPI. The value ishostname[:port]. If theport number is notspecified, the defaultport is used. Thedefault port numberfor https is 443.


code.test.comorcode.test.com:443



NO TE

In addition to supporting token-based authentication, public cloud APIs also supportauthentication using access key ID/secret access key (AK/SK). During AK/SK-basedauthentication, an SDK is used to sign the request, and the Authorization (signatureinformation) and X-Sdk-Date (time when the request is sent) header fields areautomatically added to the request.

For more details, see AK/SK-based Authentication.

The API used to obtain a user token does not require authentication. Therefore,this API only requires adding the Content-Type field. An example of such requestsis as follows:

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json

Request BodyThe body of a request is often sent in a structured format as specified in theContent-Type header field. The request body transfers all content except therequest header.

The request body varies depending on APIs. Some APIs do not require the requestbody, for example, the APIs requested using the GET and DELETE methods.

In case of the API for obtaining a user token, obtain the request parameters andparameter description in the API request. The following provides an examplerequest with a body included. Replace username, domainname, ******** (loginpassword), and xxxxxxxx (project name) with the actual values and obtain thetoken specified for the project. For example, if the project name is set to ap-southeast-1, the obtained token applies to the services in ap-southeast-1. Fordetails about how to obtain a username, domainname, and project name, seeObtaining the Username, User ID, Project Name, and Project ID.

NO TE

The scope parameter specifies where a token will take effect. You can set scope to anaccount or a project under an account. In the following example, the token takes effectonly for the resources in a specified project. For more information about this API, seeObtaining a User Token.

POST https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokensContent-Type: application/json

{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", //Replace the value with the actual username. "password": "********", //Replace the value with the actual password. "domain": { "name": "domainname" //Replace the value with the actual domain name. } } } }, "scope": { "project": {







"name": "xxxxxxxx" //Replace xxxxxxxx with the actual project name. For example, ap-southeast-1. } } } }

If all data required for the API request is available, you can send the request to callthe API through curl, Postman, or coding. In the response to the API used toobtain a user token, x-subject-token is the desired user token. You can use thistoken to authenticate the calling of other APIs.

3.3 AuthenticationRequests for calling an API can be authenticated using either of the followingmethods:

● Token-based authentication: Requests are authenticated using a token.● AK/SK-based authentication: Requests are authenticated by encrypting the

request body using an AK/SK pair.

Token-based AuthenticationNO TE

The validity period of a token is 24 hours. When using a token for authentication, cache itto prevent frequently calling the IAM API used to obtain a user token.

A token specifies temporary permissions in a computer system. During APIauthentication using a token, the token is added to requests to get permissions forcalling the API.

When calling the API to obtain a user token, you must set auth.scope in therequest body to project. Replace username, domainname, ******** (loginpassword), and xxxxxxxx (project name) with the actual values and obtain thetoken specified for the project. For example, if the project name is set to ap-southeast-1, the obtained token applies to the services in ap-southeast-1. Fordetails about how to obtain a username, domainname, and project name, seeObtaining the Username, User ID, Project Name, and Project ID.

{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", //Replace it with the actual username. "password": "********", //Replace it with the actual password. "domain": { "name": "domainname" //Replace it with the actual domain name. } } } }, "scope": { "project": { "name": "xxxxxxxx" //Replace it with the actual project name, such as ap-southeast-1. } }






} }

In Making an API Request, the process of calling the API used to obtain a usertoken is described. After a token is obtained, the X-Auth-Token header field mustbe added to requests to specify the token when calling other APIs. For example, ifthe token is ABCDEFJ...., X-Auth-Token: ABCDEFJ.... can be added to a request asfollows:

GET https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/projectsContent-Type: application/json X-Auth-Token: ABCDEFJ....

AK/SK-based AuthenticationNO TE

AK/SK-based authentication supports API requests with a body less than or equal to 12 MB.For API requests with a larger body, perform token-based authentication.

In AK/SK-based authentication, AK/SK is used to sign requests and the signature isthen added to the requests for authentication.

● AK: access key ID, which is a unique identifier used in conjunction with asecret access key to sign requests cryptographically.

● SK: secret access key used in conjunction with an AK to sign requestscryptographically. It identifies a request sender and prevents the request frombeing modified.

In AK/SK-based authentication, you can use an AK/SK to sign a request based onthe signature algorithm or use a dedicated signature SDK to sign a request. Fordetails about how to sign requests and use the signing SDK, see the API RequestSigning Guide.

If no AK/SK has been generated, access the My Credentials page, and chooseAccess Keys > Create Access Key to obtain the access keys.

NO TICE

The signing SDK is only used for signing requests and is different from the SDKsprovided by services.For details about how to obtain the AK/SK, see Obtaining the AK/SK.

3.4 Response

Status Code

After sending a request, you will receive a response, including a status code,response header, and response body.

A status code is a group of digits, ranging from 1xx to 5xx. It indicates the statusof a request. For more information, see Status Codes.





https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.html

https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.html

https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-provide.html#api-sign-provide__section5742192219435

For example, if status code 201 is returned for calling the API used to obtain auser token, the request is successful.

Response Header

Similar to a request, a response also has a header, for example, Content-Type.Table 3-4 lists the fields in the response header.

Table 3-4 Response Header

Field Description

Content-Length Length of the response body. The unit is byte.

Date Time when a request response is returned

Content-Type MIME type of the response body

Figure 3-2 shows the response header fields for the API used to obtain a usertoken. The x-subject-token header field is the desired user token. This token canthen be used to authenticate the calling of other APIs.

Figure 3-2 Header fields of the response to the request for obtaining a user token

Response Body

The body of a response is returned in structured format as specified in theContent-Type header field. The response body transfers all content except theresponse header.

The following is part of the response body for the API used to obtain a usertoken.









{ "token": { "expires_at": "2019-02-13T06:52:13.855000Z", "methods": [ "password" ], "catalog": [ { "endpoints": [ { "region_id": "aaa"//The region ID aaa is used as an example.......

If an error occurs during API calling, an error code and a message will bedisplayed. The following shows an error response body.

{ "error_msg": "The format of message is error", "error_code": "AS.0001" }

In the response body, error_code indicates the error code, and error_msg providesinformation about the error.



4 APIs

4.1 Web Image OCR

Function

Web Image OCR recognizes characters in a web image and returns the structuredresult in JSON format. For details about the constraints on using this API, seeConstraints. For details about how to use this API, see .

Prerequisites

Before using Web Image OCR, you need to apply for the service and completeauthentication. For details, see Applying for a Service and Authentication.

URL

POST https://{endpoint}/v1.0/ocr/web-image

Table 4-1 Parameter description

Parameter Mandatory

Description

endpoint Yes Domain name or IP address of the serverbearing the REST service endpoint. The endpointvaries depending on services in different regions.For more details, see Endpoints.

Request Message

Table 4-2 describes the request parameters of Web Image OCR.

Optical Character RecognitionAPI Reference 4 APIs


https://support.huaweicloud.com/intl/en-us/productdesc-ocr/ocr_01_0006.html#section0

Table 4-2 Request parameters

Parameter Mandatory

Type Description

image No. Seteither thisparameteror url.

String Base64 character string convertedfrom the image. The size cannotexceed 10 MB.The narrow edge contains at least15 pixels and the wide edgecontains a maximum of 8,192pixels. The JPEG, JPG, PNG, BMP,TIFF, GIF, and WebP formats aresupported.

url No. Seteither thisparameteror image.

String Image URL. Currently, thefollowing URLs are supported:● Public network: HTTP/HTTPS

URL.● URL provided by OBS. You need

to be authorized for using OBSdata. Required authorizationsinclude service authorization,temporary authorization, andanonymous publicauthorization. For details, seeConfiguring AccessPermissions of OBS.

NOTE● The API response time depends on

the image download time. If theimage download takes a longtime, the API call will fail.

● Ensure that the storage servicewhere the images reside is stableand reliable. OBS is recommendedfor storing image data.

detect_direction No Boolean Indicates whether the function ofaligning a tilted image is enabled.The options are as follows:● true: The tilted image is

aligned.● false: The tilted image is not

aligned.An image tilted at any angle canbe aligned. If this parameter is notspecified, the default value false isused.



Parameter Mandatory

Type Description

extract_type No Array ofstrings

Structured data extractionparameter list. Currently, only thecontact information and imagewidth and height are supported.The input parameter values arecontact_info and image_size,respectively.If this parameter is not set or isdeleted, this parameter will not beused.

Response MessageTable 4-3 describes the response parameters of Web Image OCR.

Table 4-3 Response parameters

Parameter Type Description

result Object Calling result of a successful API call.This parameter is not included if theAPI call fails.

words_block_count Integer Number of detected text blocks.

words_block_list Array ofobjects

List of text blocks to be recognized.The output sequence is from left toright and from top to bottom.

words String Recognition result of a text block

location Array ofobjects

List of location information about atext block, including the coordinates (x,y) of vertexes of the text block, wherethe coordinate origin is the upper-leftvertex of the image. The x-axis ishorizontal, and the y-axis is vertical.

extracted_data Object Extracted structured JSON result. Thekey value is the same as that ofextract_type in the request parameterlist. Currently, only contact informationcan be extracted, that is, contact_info.If extract_type is left blank or missing,no information is extracted.




contact_info Object Extracted contact information,including the name, phone number,province, city, and detailed address.If extract_type does not contain thisparameter, this parameter does notexist in the response.

image_size Object Width and height of an image.If extract_type does not contain thisparameter, this parameter does notexist in the response.

height Integer Image height, which is returned whenimage_size is passed.

width Integer Image width, which is returned whenimage_size is passed.

name String Name, which is returned whencontact_info is passed.

phone String Contact phone number, which isreturned when contact_info is passed.

province String Province, which is returned whencontact_info is passed.

city String City, which is returned whencontact_info is passed.

district String County or district, which is returnedwhen contact_info is passed.

detail_address String Detailed address (excluding theprovince, city, and county or district),which is returned when contact_info ispassed.

confidence Float Confidence information of a relatedfield. The value ranges from 0 to 1.A higher confidence level indicates ahigher reliability and accuracy of thecorresponding field identified.The confidence is not equal to theaccuracy, and is calculated throughrelated algorithms.




error_code String Error code of a failed API call. Fordetails, see Error Codes.If the error code ModelArts.4204 isdisplayed, refer to Why Is a MessageStating "ModelArts.4204" DisplayedWhen the OCR API Is Called.This parameter is not included whenthe API is successfully called.

error_msg String Error message of a failed API call.

ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on toservices and regions. For details, see Endpoints.For example, the endpoint of Web Image OCR in the AP-Bangkok region is ocr.ap-southeast-2.myhuaweicloud.com, so the request URL is https://ocr.ap-southeast-2.myhuaweicloud.com/v1.0/web-image.

● For details about how to obtain a token, see Making an API Request.

● Request example (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v1.0/ocr/web-image Request Header:Content-Type: application/json,X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...

Request Body: { "image":"/9j/4AAQSkZJRgABAgEASABIAAD/..." }

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://{endpoint}/v1.0/ocr/web-image Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG... Request Body:{ "url":"https://BucketName.obs.xxxx.com/ObjectName"}

● Sample code for a Python request (For details about other languages, see thefollowing sample code or use the OCR SDK.)# encoding:utf-8

import requestsimport base64

url = "https://{endpoint}/v1.0/ocr/web-image"token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/web-image-demo.png'



https://support.huaweicloud.com/intl/en-us/ocr_faq/ocr_01_0031.html



with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images.payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Response example{ "result": { "words_block_count": 2, "words_block_list": [ { "words": "words recognized from the image", "confidence": 0.9950, "location": [ [13, 476], [91, 332], [125, 351], [48, 494] ] }, { "words": "words recognized from the image", "confidence": 0.9910, "location": [ [13, 476], [91, 332], [125, 351], [48, 494] ] } ], "extracted_data": {} } }

● Failed response example{ "error_code": "AIS.0103", "error_msg": "The image size does not meet the requirements." }

Status CodeFor details about the status code, see Status Codes.

Error CodeFor details about the error code, see Error Codes.

4.2 Passport OCR

FunctionPassport OCR recognizes the text on the first page of a passport and returns thestructured information in JSON format.

Passport OCR can recognize all fields on a Chinese passport. A foreign passportcan be identified by the machine-readable code at the bottom of the passportwith 6 to 7 key fields extracted from the code. For details about the constraints onusing this API, see Constraints. For details about how to use this API, seeIntroduction to OCR.




https://support.huaweicloud.com/intl/en-us/qs-ocr/ocr_05_0001.html

PrerequisitesBefore using Passport OCR, you need to apply for the service and completeauthentication. For details, see Applying for a Service and Authentication.

URLPOST https://{endpoint}/v1.0/ocr/passport


Parameter Mandatory

Description


Request MessageTable 4-5 describes the request parameters of Passport OCR.


Parameter Mandatory

Type Description


String Base64 character string convertedfrom the image. The size cannotexceed 10 MB.The narrow edge contains at least15 pixels and the wide edgecontains at most 4,096 pixels. TheJPEG, JPG, PNG, BMP, and TIFFformats are supported.



Parameter Mandatory

Type Description



URL.● URL provided by OBS. You need

to be authorized to use OBSdata, including serviceauthorization, temporaryauthorization, and anonymouspublic authorization. Fordetails, see Configuring AccessPermissions of OBS.




country_code No String Country code on the passport. Therecognition mode is determinedbased on the country code.● If this parameter is left blank,

OCR automatically matches therecognition mode based on thepassport type identified by theservice.

● If you set this parameter toGENERAL, the passport isrecognized based on themachine-readable code.

● If this parameter is set to CHN,all fields in the Chinesepassport are recognized.

Response MessageTable 4-6 describes the response parameters of Passport OCR.





result Object Calling result of a successful API call.This parameter is not included whenthe API call fails.

passport_type String Passport type. Possible values are asfollows:● P: ordinary passport● W: diplomatic passport● G: service passport

country_code String Country code

passport_number String Passport ID

nationality String Nationality of the passport holder

surname String Last name

given_name String Given game

sex String Gender.

date_of_birth String Date of birth

date_of_expiry String Date on which the passport expires

date_of_issue String Date of issue

place_of_birth String Place of birth

place_of_issue String Place where the passport is issued

issuing_authority String Authority that issues the passport.The abbreviation of the issuingauthority of each consulate is notunified. The abbreviation of Chineseissuing authority is P.R.China. Forexample, if the issuing authority isP.R.C, the recognition result isP.R.China.

confidence Object Confidence information of a relatedfield. The value ranges from 0 to 1.Confidence of related fields. A higherconfidence indicates a more accurateresult.The confidence is not equal to theaccuracy, and is calculated throughrelated algorithms.



extra_info Object By default, this parameter is left blank.For a Chinese passport, extra_infocontains Chinese character-describedfields on the passport, such as thename and place of birth.


error_msg String Error message of a failed API call.This parameter is not included whenthe API is successfully called.

ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on servicesand regions. For details, see Endpoints.

For example, the endpoint of Passport OCR in the AP-Hong Kong region is ocr.ap-southeast-1.myhuaweicloud.com, so the request URL is https://ocr.ap-southeast-1.myhuaweicloud.com/v1.0/ocr/passport.


● Request example (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v1.0/ocr/passport Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body:{ "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...", "country_code": "GENERAL"}

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://{endpoint}/v1.0/ocr/passport Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body:{ "url":"https://BucketName.obs.xxxx.com/ObjectName", "country_code": "GENERAL"}

● Sample code for a Python request (For details about other languages, see thefollowing sample code or use the OCR SDK.)






# encoding:utf-8


url = "https://{endpoint}/v1.0/ocr/passport"token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/passport-demo.png'with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images.payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Response example– Example 1: Chinese passport

{ "result": { "passport_type": "P", "country_code": "CHN", "passport_number": "ED999XXXX", "nationality": "CHINESE", "surname": "ZHANG", "given_name": "SAN", "sex": "F", "date_of_birth": "1990-12-12", "date_of_expiry": "2020-07-08", "date_of_issue": "2010-07-09", "place_of_birth": "HUNAN", "place_of_issue": "GUANGDONG", "issuing_authority": "MPS Exit & Entry Administration", "extra_info": { "local_language": { "name": "name recognized from the image", "sex": "sex recognized from the image", "place_of_birth": "place of birth recognized from the image", "place_of_issue": "place of issue recognized from the image", "issuing_authority": "issuing authority recognized from the image", "nationality": "nationality recognized from the image", } }, "confidence": { "passport_type": 1.0, "country_code": 1.0, "passport_number": 0.9997, "nationality": 1.0, "surname": 0.9729, "given_name": 0.9729, "sex": 1.0, "date_of_birth": 0.9998, "date_of_expiry": 0.9995, "date_of_issue": 0.9969, "place_of_birth": 1.0, "place_of_issue": 1.0, "issuing_authority": 0.9985 } }}

– Example 2: Foreign passport{ "result": { "country_code": "ETF", "surname": "HUZHAO", "given_name": "ZHAOMIN DESALEGN ", "passport_number": "EP435XXXX", "date_of_birth": "1985-09-18",



"sex": "M", "date_of_expiry": "2022-01-15", "machine_code": "P<ETFHUZHAO<< ZHAOMIN <DESALEGN<<<<<<<<<<<<<<<", "machine_code2": "EP435XXXX7ETF8509185M2201155<<<<<<<<<<<<<<08", "extra_info": {}, "confidence": { "country_code": 0.9727, "surname": 0.9727, "given_name": 0.9727, "passport_number": 0.9558, "date_of_birth": 0.9558, "sex": 0.9558, "date_of_expiry": 0.9558 } }}


Status Code

For details about the status code, see Status Codes.

Error Code

For details about the error code, see Error Codes.

4.3 Thailand ID Card OCR

Function

Thailand ID Card OCR recognizes characters on a Thailand-issued nationalregistration card and returns the structured result in JSON format. For detailsabout the constraints on using this API, see Constraints. For details about how touse this API, see Introduction to OCR.

Figure 4-1 Thailand ID Card OCR example





PrerequisitesBefore using Thailand ID Card OCR, you need to apply for the service andcomplete authentication. For details, see Applying for a Service andAuthentication.

URLPOST https://{endpoint}/v1.0/ocr/thailand-id-card


Parameter Mandatory

Description

endpoint Yes Domain name or IP address of the serverbearing the REST service endpoint. The endpointvaries depending on services in different regions.For details, see Endpoints.

Request MessageTable 4-8 describes the request parameters of Thailand ID Card OCR.


Parameter Mandatory Type Description

image No. Set eitherthis parameteror url.

String Base64 character string convertedfrom the image. The size cannotexceed 10 MB.The narrow edge contains at least15 pixels and the wide edgecontains at most 8,192 pixels. TheJPEG, JPG, PNG, BMP, and TIFFformats are supported.




url No. Set eitherthis parameteror image.


URL● URL provided by OBS. You

need to be authorized to useOBS data. Requiredauthorizations include serviceauthorization, temporaryauthorization, and anonymouspublic authorization. Fordetails, see Configuring AccessPermissions of OBS.




side No String ● front: front of an ID card.● back: back of an ID card.If this parameter is left empty ornot included, the systemautomatically recognizes whetherthe image is the front or back ofan ID card. To ensure accuracy, setthis parameter.

return_portrait_image

No Boolean Specifies whether to return thehead portrait. Possible values areas follows:● true: The Base64 code of the

head portrait on the ID card isreturned.

● false: The Base64 code of thehead portrait on the ID card isnot returned.

If this parameter is nottransferred, the default valuefalse is used. That is, the Base64code of the head portrait on theID card is not returned.




return_portrait_location

No Boolean Specifies whether to return thelocation of the head portrait onthe ID card. Possible values are asfollows:● true: The location of the head

portrait on the ID card isreturned.

● false: The location of the headportrait on the ID card is notreturned.

return_idcard_type

No Boolean Specifies whether to return the IDcard type. Possible values are asfollows:● true: The ID card type is

returned, including the originalID card and the copy of the IDcard.

● false: The ID card type is notreturned.

Response MessageTable 4-9 describes the response parameters of Thailand ID Card OCR.



result Object Calling result of a successful API call

id_number String ID number

name_th String Thai name

first_name_en String English given name

last_name_en String English surname

date_of_birth_th String Date of birth, in Thai

date_of_birth_en String Date of birth, in English

religion_th String Religion

address_th String Address on the ID card

date_of_issue_th String Date of issue, in Thai

date_of_issue_en String Date of issue, in English




date_of_expiry_th String Date of expiry, in Thai

date_of_expiry_en String Date of expiry, in English

serial_number String Serial number

card_number String ID number on the back of the ID card

laser_number String Laser code

confidence Object Confidence information of a related field.The value ranges from 0 to 1.A higher confidence indicates a higherreliability of the corresponding fieldidentified this time. In the statisticalsense, a higher confidence indicates ahigher accuracy.The confidence is not equal to theaccuracy, and is calculated throughrelated algorithms.

portrait_image String Base64 code of the head portrait.This parameter is available only whenreturn_portrait_image is set to true.

portrait_location Array ofobjects

Location of the head portrait on theoriginal image.This parameter is available only whenreturn_portrait_location is set to true.The image is displayed in a list. The listcontains the two-dimensional coordinates(x,y) of the four vertices in the headportrait area. The origin of thecoordinates is the upper left corner of theimage. The x axis is horizontal, and the yaxis is vertical.

idcard_type String ID card type. Possible values are asfollows:● normal: original ID card● copy: copy of the ID cardThis parameter is available only whenreturn_idcard_type is set to true.




error_code String Error code of a failed API call. For details,see Error Codes.If the error code ModelArts.4204 isdisplayed, refer to Why Is a MessageStating "ModelArts.4204" DisplayedWhen the OCR API Is Called.This parameter is not included when theAPI is successfully called.

error_msg String Error message of a failed API call.This parameter is not included when theAPI is successfully called.

ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on servicesand regions. For details, see Endpoints.

For example, the endpoint of Thailand ID Card OCR in the AP-Bangkok region is ocr.ap-southeast-2.myhuaweicloud.com, so the request URL is https://ocr.ap-southeast-2.myhuaweicloud.com/v1.0/thailand-id-card.


● Request example (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v1.0/ocr/thailand-id-card

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAMAA...", "side":"front", "return_portrait_image":true, "return_portrait_location ":true, "return_idcard_type":true}

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://{endpoint}/v1.0/ocr/thailand-id-card

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "url":"https://BucketName.obs.xxxx.com/ObjectName"}


import requests






import base64

url = "https://{endpoint}/v1.0/ocr/thailand-id-card"token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/thailand-id-card-demo.png'with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images. payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Successful response example (the front){ "result": { "id_number": "X XXXX XXXXX XX X", "name_th": "XXX", "first_name_en": "XX", "last_name_en": "XX", "date_of_birth_th": "5 ก.พ. 2493", "date_of_birth_en": "5 Feb. 1950", "religion_th": "XX", "address_th": "XXXXX", "date_of_issue_th": "XX", "date_of_issue_en": "4 Mar. 2011", "date_of_expiry_th": "22 ก.พ. 2561", "date_of_expiry_en": "22 Feb. 2018", "serial_number": "XXXX-XX-XXXXX", "confidence": { "id_number": 0.9999, "name_th": 0.9994, "first_name_en": 0.998, "last_name_en": 0.9997, "date_of_birth_th": 0.9996, "date_of_birth_en": 0.9997, "religion_th": 0.686, "address_th": 0.624, "date_of_issue_th": 1, "date_of_issue_en": 1, "date_of_expiry_th": 0.9969, "date_of_expiry_en": 0.61, "serial_number": 0.9887 }, "portrait_image": "/9j/4AA... ", "portrait_location": [ [576, 237], [741, 237], [739, 430], [574, 431] ], "idcard_type": "normal" }}

● Successful response example (the back){ "result": { "card_number": "XXXX-XXX-XX", "laser_number": "XXXX-XXXXXXX-XX", "confidence": { "id_number": 0.9999, "laser_number": 0.9994 } }}

● Failed response example{ "error_code": "AIS.0103",



"error_msg": "The image size does not meet the requirements." }



4.4 Myanmar ID Card OCR

FunctionMyanmar ID Card OCR recognizes information on Myanmar-issued nationalregistration cards. For details about the constraints on using this API, seeConstraints. For details about how to use this API, see Introduction to OCR.

Figure 4-2 Myanmar ID Card OCR example

PrerequisitesBefore using Myanmar ID Card OCR, you need to apply for the service andcomplete authentication. For details, see Applying for a Service andAuthentication.

URLPOST https://{endpoint}/v1.0/myanmar-id-card






Parameter Mandatory

Description


Request MessageTable 4-11 describes the request parameters of Myanmar ID Card OCR.


Parameter Mandatory

Type Description

image No.Seteitherthisparameteror url.

String Base64 character string convertedfrom the image. The size cannotexceed 10 MB.The narrow edge contains at least 15pixels and the wide edge contains atmost 8,000 pixels. The JPEG, JPG, PNG,BMP, and TIFF formats are supported.

url No.Seteitherthisparameterorimage.

String Image URL. Currently, the followingURLs are supported:● Public network: HTTP/HTTPS URL.● URL provided by OBS. You need to

be authorized to use OBS data.Required authorizations includeservice authorization, temporaryauthorization, and anonymouspublic authorization. For details,see Configuring AccessPermissions of OBS.

NOTE● The API response time depends on the

image download time. If the imagedownload takes a long time, the APIcall will fail.

● Ensure that the storage service wherethe images reside is stable and reliable.OBS is recommended for storing imagedata.



Parameter Mandatory

Type Description

convert_unicode No Boolean ● true: The output is in the unicodeformat.

● false: The output is in the zawgyiformat.

If this parameter is left blank or doesnot exist, the output format is zawgyiby default.

return_confidence No Boolean Whether to return the confidence.Possible values are as follows:true: Return the confidence.false: Do not return the confidence.If this parameter is not specified, thesystem does not return the confidenceby default. If the input parameter isnot of the Boolean type, an errormessage is displayed, indicating thatthe parameter is invalid.

return_portrait_image

No Boolean Specifies whether to return the headportrait. Possible values are as follows:● true: The Base64 code of the head

portrait on the ID card is returned.● false: The Base64 code of the head

portrait on the ID card is notreturned.

If this parameter is not transferred,the default value false is used. That is,the Base64 code of the head portraiton the ID card is not returned.

return_portrait_location

No Boolean Specifies whether to return thelocation of the head portrait on the IDcard. Possible values are as follows:● true: The location of the head

portrait on the ID card is returned.● false: The location of the head

portrait on the ID card is notreturned.



Parameter Mandatory

Type Description

return_idcard_type No Boolean Specifies whether to return the IDcard type. Possible values are asfollows:● true: The ID card type is returned,

including the original ID card andthe copy of the ID card.

● false: The ID card type is notreturned.

Response Message

Table 4-12 describes the response parameters of Myanmar ID Card OCR.




side String Front or back of a national registrationcard. Possible values are front or back.

class String ● ID card type. Possible values are asfollows:

● new_version: new version of ID card● old_version: old version of ID card

nrc_id String ID card No.

issue_date String Date of issue

name String Name

father_name String Father's name

birth String Date of birth

bloodlines_religion String Ethnic group or religion

height String Height

blood_group String Blood type

card_id String National registration card number on theback

nrc_id_back String National registration card ID on the back

profession String Occupation

address String Address




confidence Object Confidence information of a related field.The value ranges from 0 to 1.A higher confidence indicates a higherreliability of the corresponding fieldidentified this time. In the statisticalsense, a higher confidence indicates ahigher accuracy.The confidence is calculated by thealgorithm and is not equal to theaccuracy of the field.

portrait_image String Base64 code of the head portrait.This parameter is available only whenreturn_portrait_image is set to true.

portrait_location Array ofobjects

Location of the head portrait on theoriginal image.This parameter is available only whenreturn_portrait_location is set to true.The image is displayed in a list. The listcontains the two-dimensional coordinates(x,y) of the four vertices in the headportrait area. The origin of thecoordinates is the upper left corner of theimage. The x axis is horizontal, and the yaxis is vertical.

idcard_type String ID card type. Possible values are asfollows:● normal: original ID card● copy: copy of the ID cardThis parameter is available only whenreturn_idcard_type is set to true.

error_code String Error code of a failed API call. For details,see Error Codes.If the error code ModelArts.4204 isdisplayed, refer to Why Is a MessageStating "ModelArts.4204" DisplayedWhen the OCR API Is Called.This parameter is not included when theAPI is successfully called.

error_msg String Error message of a failed API call.This parameter is not included when theAPI is successfully called.






ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on servicesand regions. For details, see Endpoints.For example, the endpoint of Myanmar ID Card OCR in the AP-Hong Kong region isocr.ap-southeast-1.myhuaweicloud.com, so the request URL is https://ocr.ap-southeast-1.myhuaweicloud.com/v1.0/myanmar-id-card.


● Request example (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v1.0/myanmar-id-card

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAAgABwESAAd...", "convert_unicode": true, "return_confidence": true, "return_portrait_image": true, "return_portrait_location": true, "return_idcard_type": true}

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://{endpoint}/v1.0/myanmar-id-card

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "url":"https://BucketName.obs.xxxx.com/ObjectName", "convert_unicode": true, "return_confidence": true, "return_portrait_image": true, "return_portrait_location": true, "return_idcard_type": true}



url = "https://{endpoint}/v1.0/ocr/myanmar-id-card"token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/myanmar-id-card-demo.png'with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images.payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Successful response example (the front){ "result":{ "side": "front",



"nrc_id": "XXXXXXXX", "issue_date": "၂၂.၂.၂၂၂၂", "name": "XXXX", "father_name": "XXX", "birth": "၂၂.၂၂.၂၂၂၂", "bloodlines_religion": "၂၂၂၂၂၂၂၂၂", "height": "၂'၂\"", "blood_group": "၂၂", "class": "new_version", "confidence": { "nrc_id": 0.7514, "issue_date": 0.5385, "name": 0.6641, "birth": 0.5216, "bloodlines_religion": 0.9774, "height": 0.7526, "blood_group": 0.7541 }, "idcard_type": "normal", "portrait_image": "/9j/4AAQSkZJRgABAgEASABIABRHFGD...", "portrait_location": [ [106, 178], [369, 181], [366, 448], [108, 445] ] }}

● Successful response example (the back){ "result":{ "side": "back", "card_id": "XXXXXXX", "nrc_id_back": "", "profession": "၂၂၂၂၂၂၂၂၂၂", "address": "XXXXXXXX", "class": "new_version", "confidence": { "card_id": 0.9878, "nrc_id_back": 0.9595, "profession": 0.9995, "address": 0.9299 }, "idcard_type": "normal" }}






4.5 Myanmar Driving License OCR

Function

Myanmar Driving License OCR recognizes characters on a Myanmar-issued driver'slicense and returns the structured result in JSON format. For details about theconstraints on using this API, see Constraints. For details about how to use thisAPI, see Introduction to OCR.

Figure 4-3 Myanmar Driving License OCR example

Prerequisites

Before using Myanmar Driving License OCR, you need to apply for the service andcomplete authentication. For details, see Applying for a Service andAuthentication.

URL

POST https://{endpoint}/v1.0/ocr/myanmar-driver-license


Parameter Mandatory

Description

endpoint Yes Domain name or IP address of the serverbearing the REST service endpoint. The endpointvaries between services in different regions. Itcan be obtained from Endpoints.

Request Message

Table 4-14 describes the request parameters of Myanmar Driving License OCR.








String Base64 character string converted fromthe image. The size cannot exceed 10MB.The narrow edge contains at least 15pixels and the wide edge contains atmost 4,096 pixels. The JPEG, JPG, PNG,BMP, and TIFF formats are supported.


String Image URL. Currently, the followingURLs are supported:● Public network: HTTP/HTTPS URL.● URL provided by OBS. You need to

be authorized to use OBS data,including service authorization,temporary authorization, andanonymous public authorization. Fordetails, see Configuring AccessPermissions of OBS.

NOTE● The API response time depends on the

image download time. If the imagedownload takes a long time, the API callwill fail.

● Ensure that the storage service wherethe images to be detected reside isstable and reliable. OBS isrecommended for storing image data.

convert_unicode

No Boolean ● true: The output is in the unicodeformat.

● false: The output is in the zawgyiformat.

If this parameter is left blank or doesnot exist, the output format is zawgyiby default.

Response MessageTable 4-15 describes the response parameters of Myanmar Driving License OCR.







card_number String Number of the Myanmar drivinglicense

card_number_en String Number of the English driving license

name String Name, in Burmese

name_en String Name, in English

nrc_id String National registration card number, inBurmese

nrc_id_en String National registration card number, inEnglish

Birth String Date of birth, in Burmese

birth_en String Date of birth, in English

blood_group String Blood type, in Burmese

blood_group_en String Blood type, in English

expiried_date String Date of expiry, in Burmese

expiried_date_en String Date of expiry, in English

confidence Object Confidence information of a relatedfield. The value ranges from 0 to 1.A higher confidence indicates a higherreliability of the corresponding fieldidentified this time. In the statisticalsense, a higher confidence indicates ahigher accuracy.The confidence is not equal to theaccuracy, and is calculated throughrelated algorithms.








ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on servicesand regions. For details, see Endpoints.For example, the endpoint of Myanmar Driving License OCR in the AP-Hong Kongregion is ocr.ap-southeast-1.myhuaweicloud.com, so the request URL is https://ocr.ap-southeast-1.myhuaweicloud.com/v1.0/ocr/myanmar-driver-license.


● Request example (Method 1: Use a Base64-encoded image.)POST https://{endpoint}/v1.0/ocr/myanmar-driver-license

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...", "convert_unicode": true}

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://{endpoint}/v1.0/ocr/myanmar-driver-license

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "url":"https://BucketName.obs.xxxx.com/ObjectName", "convert_unicode": true}



url = "https://{endpoint}/v1.0/ocr/myanmar-driver-license"token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/myanmar-driver-license-demo.png'with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images.payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Response example




Status Code

For details about the status code, see Status Codes.



Error Code

For details about the error code, see Error Codes.

4.6 Chile ID Card OCR

Function

Chile ID Card OCR recognizes the text in a Chile ID card image and returns therecognition result in JSON format. For details about the constraints on using thisAPI, see Constraints. For details about how to use this API, see Introduction toOCR.

Figure 4-4 Chile ID Card OCR example

Prerequisites

Before using Chile ID Card OCR, you need to apply for the service and completeauthentication. For details, see Applying for a Service and Authentication.

URL

POST https://{endpoint}/v2/{project_id}/ocr/chile-id-card


Parameter Mandatory

Description

endpoint Yes Domain name or IP address of the serverbearing the REST service endpoint. The endpointvaries depending on services in different regions.The endpoint of the Chile ID Card OCR API isocr.la-south-2.myhuaweicloud.com.

project_id Yes Project ID, which can be obtained fromObtaining a Project ID.






Request MessageTable 4-17 describes the request parameters of Chile ID Card OCR.



image Yes String Image data (Base64-encoded). Theimage size must be greater than orequal to 15 x 15 pixels and themaximum width is 8,192 pixels. TheJPG, PNG, BMP, and TIFF formats aresupported.

url Configureeither thisparameteror image.

String URL of the image file. Currently, URLsfor anonymously and publiclyauthorized or external access to imagefiles stored on OBS are supported.

Response MessageThe following table describes the response parameters of Chile ID Card OCR.



result Object Calling result of a successful API call.If the API fails to be called, thisparameter is left empty.

surname List Last name.

given_name String First name.

nationality String Nationality.

sex String Gender.

birth String Date of birth.

issue_date String Issue date.

expiry_date String Validity period.

document_number String Document No.

number String ID number.






ExampleNO TE

● The endpoint is the request URL for calling an API. Endpoints vary depending on servicesand regions. For details, see Endpoints.For example, the endpoint of Chile ID Card OCR deployed in the LA-Santiago region isocr.la-south-2.myhuaweicloud.com. The request URL is https://ocr.la-south-2.myhuaweicloud.com/v2/{project_id}/ocr/chile-id-card. project_id indicatesthe project ID. For details about how to obtain the project ID, see Obtaining a ProjectID.


● Request example (Method 1: Use a Base64-encoded image.)POST https://ocr.la-south-2.myhuaweicloud.com/v2/{project_id}/ocr/chile-id-card

Request Header: Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body:{ "image": "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgA..."}

● Request example (Method 2: Use the URL redirecting to the image file.)POST https://ocr.la-south-2.myhuaweicloud.com/v2/{project_id}/ocr/chile-id-card

Request Header:Content-Type: application/jsonX-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...Request Body: { "url":"https://BucketName.obs.xxxx.com/ObjectName"}



url = "https://ocr.la-south-2.myhuaweicloud.com/v2/{project_id}/ocr/chile-id-card"






token = "Actual token value obtained by the user"headers = {'Content-Type': 'application/json', 'X-Auth-Token': token}

imagepath = r'./data/myanmar-driver-license-demo.png'with open(imagepath, "rb") as bin_data: image_data = bin_data.read()image_base64 = base64.b64encode(image_data).decode("utf-8") # Base64 encoding of images.payload = {"image": image_base64} # url or image.response = requests.post(url, headers=headers, json=payload)print(response.text)

● Successful Response Example{ "result": { "surname": [ "FERNANDEZ", "GATICA" ], "given_name": "MARCELA CAROLINA", "nationality": "CHILENA", "sex": "F", "birth": "21 FEB 1982", "document_number": "100000001", "issue_date": "1 SEP 2013", "expiry_date": "10 AGO 2023", "number": "12.749.625-K", "confidence": { "surname": 0.9584, "given_name": 0.8106, "nationality": 0.7026, "sex": 0.5879, "birth": 0.9305, "document_number": 0.8181, "issue_date": 0.8518, "expiry_date": 0.7757, "number": 0.9528 } }}

● Failed response example{ "error_code": "AIS.0103", "error_msg": "The image size does not meet the requirements."}

Status CodesFor details about the status code, see Status Codes.

Error CodesFor details about the error code, see Error Codes.



5 Appendix

5.1 Status CodesThe following table lists the common status codes.

StatusCode

Coding Description

100 Continue The server has received the initial part of therequest and the client should continue tosend the remaining part.It is issued on a provisional basis whilerequest processing continues. It alerts theclient to wait for a final response.

101 Switching Protocols The requester has asked the server to switchprotocols and the server has agreed to do so.The target protocol must be more advancedthan the source protocol.For example, the current HTTPS protocol isswitched to a later version.

200 OK The server has successfully processed therequest.

201 Created The request has been fulfilled, resulting inthe creation of a new resource.

202 Accepted The request has been accepted, but theprocessing has not been completed.

203 Non-AuthoritativeInformation

The server has successfully processed therequest, but is returning information thatmay be from another source.

Optical Character RecognitionAPI Reference 5 Appendix


StatusCode

Coding Description

204 No Content The server has successfully processed therequest, but does not return any content.The status code is returned in response to anHTTP OPTIONS request.

205 Reset Content The server has successfully processed therequest, but does not return any content.Unlike a 204 response, this response requiresthat the requester reset the content.

206 Partial Content The server has successfully processed a partof the GET request.

300 Multiple Choices There are multiple options for the location ofthe requested resource. The responsecontains a list of resource characteristics andaddresses from which the user or user agent(such as a browser) can choose the mostappropriate one.

301 Moved Permanently The requested resource has been assigned anew permanent URI, and the new URI iscontained in the response.

302 Found The requested resource resides temporarilyunder a different URI.

303 See Other The response to the request can be foundunder a different URI, and should beretrieved using a GET or POST method.

304 Not Modified The requested resource has not beenmodified. In such a case, there is no need toretransmit the resource since the client has apreviously-downloaded copy.

305 Use Proxy The requested resource must be accessedthrough a proxy.

306 Unused The HTTP status code is no longer used.

400 Bad Request The request is invalid.The client should not repeat the requestwithout modifications.

401 Unauthorized The authorization information provided bythe client is incorrect or invalid.

402 Payment Required This status code is reserved for future use.



StatusCode

Coding Description

403 Forbidden The server has received the request andunderstood it, but refuse to respond to it.The client should modify the request insteadof re-initiating it.

404 Not Found The requested resource cannot be found.The client should not repeat the requestwithout modifications.

405 Method Not Allowed The method specified in the request is notsupported for the requested resource.The client should not repeat the requestwithout modifications.

406 Not Acceptable The server cannot fulfill the requestaccording to the content characteristics ofthe request.

407 Proxy AuthenticationRequired

This status code is similar to 401, butindicates that the client must firstauthenticate itself with the proxy.

408 Request Timeout The server has timed out waiting for therequest.The client may repeat the request withoutmodifications at a later time.

409 Conflict The request could not be processed due to aconflict.For example, an edit conflict betweenmultiple simultaneous updates or theresource that the client attempts to createalready exists.

410 Gone The requested resource has been deletedpermanently and is no longer available.The status code indicates that the requestedresource has been deleted permanently.

411 Length Required The server refuses to accept the requestwithout a defined Content-Length.

412 Precondition Failed The server did not meet one of thepreconditions contained in the request.



StatusCode

Coding Description

413 Request Entity TooLarge

The request is larger than the server iswilling or able to process. The server mayclose the connection to prevent the clientfrom continuing the request. If the server isonly temporarily unable to process therequest, the response will contain a Retry-After header field.

414 Request URI Too Long The Request-URI is too long for the server toprocess.

415 Unsupported MediaType

The server is unable to process the mediaformat in the request.

416 Requested Range NotSatisfiable

The requested range is invalid.

417 Expectation Failed The server has failed to meet therequirements of the Expect request-headerfield.

422 Unprocessable Entity The request is well-formed but cannot beprocessed due to semantic errors.

429 Too Many Requests The client has sent an excessive number ofrequests to the server within a given time(exceeding the limit on the access frequencyof the client), or the server has received anexcessive number of requests within a giventime (beyond its processing capability). Inthis case, the client should resend therequests at any point after the time specifiedin the Retry-After header of the response.

500 Internal Server Error The server is able to receive the request butunable to understand it.

501 Not Implemented The server does not support the functionrequired to fulfill the request.

502 Bad Gateway The server was acting as a gateway or proxyand received an invalid response from theupstream server.

503 Service Unavailable The requested service is invalid.The client should not repeat the requestwithout modifications.

504 Gateway Timeout The request cannot be fulfilled within agiven time. This status code is returned tothe client only if the Timeout parameter isspecified in the request.



StatusCode

Coding Description

505 HTTP Version NotSupported

The server does not support the HTTPSprotocol version used in the request.

5.2 Error CodesIf an error occurs during API calling, no result is returned. You can locate the causeof an error using the error code of each API. When an API call fails, HTTPS statuscode 4xx or 5xx is returned. The returned message body contains a specific errorcode and error message. If you are unable to identify the cause of an error,contact the HUAWEI CLOUDcustomer service and provide the error code so thatwe can help you resolve the problem at the earliest.

Format of an Error Response Body

If an error occurs during API calling, an error code and a message will bedisplayed. The following shows an error response body.

{ "error_msg": "The input parameter is invalid.", "error_code": "AIS.0101" }

In the response body, error_code indicates the error code, and error_msg providesinformation about the error.

Error Codes

OCR is deployed on ModelArts and uses API Gateway (APIG). Therefore, OCR errorcodes include ModelArts and APIG platform error codes.

If an error code starting with APIGW is returned after you call an API, resolve theproblem by referring to the instructions provided in Error Codes.

Module

ErrorCode

Error Message. Description Solution

OCR AIS.0101 The inputparameter isinvalid.

The inputparameter doesnot meet therequirements.

Check the enteredparameter. Fordetails about theinput parameterformat of each API,see OpticalCharacterRecognition APIReference > APIs >Requestparameters.



https://support.huaweicloud.com/intl/en-us/devg-apisign/api-sign-errorcode.html

Module

ErrorCode


AIS.0102 The image formatis not supported.

The imageformat is notsupported.

Check the imageformat. For detailsabout the imageformats supportedby each service, seeConstraints.

AIS.0103 The image sizedoes not meet therequirements.

The image sizedoes not meettherequirements.

Check the imagesize. For detailsabout the imagesize supported byeach service, seeConstraints.

AIS.0104 The image is notsupported or theimage quality ispoor.

The image isnot supportedor is of poorquality.

Check the imagetype and quality.

AIS.0105 Recognition failed. Algorithmcalculationfailed.

Contact HUAWEICLOUD supportpersonnel.

Platform

ModelArts.0203

Invalid token. The token isinvalid.

Check whether thetoken is correct.

ModelArts.4101

Token headercannot be empty.

The token isempty.

The HTTP requestheader does notcontain the tokenrequestauthenticationinformation of x-auth-token. Checkthe request.

ModelArts.4102

Parse Token error. The tokenfailed to beparsed.

The token requestauthenticationinformation of x-auth-token in theHTTP requestheader is incorrect.Check the sentrequest and token.

ModelArts.4103

Invalid Tokenheader.

The token isinvalid.

The token requestauthenticationinformation of x-auth-token in theHTTP requestheader is incorrect.Check the sentrequest and token.





https://www.huaweicloud.com/intl/en-us/contact-sales.html



Module

ErrorCode


ModelArts.4104

Invalid RequestContent Length.

The length ofthe requestbody is invalid.

Check the requestbody length.

ModelArts.4105

The JSON formatof the input data isincorrect.

The JSONformat of therequest body isincorrect.

Check the JSONformat of therequest body.

ModelArts.4106

Invalidauthorizationrequest.

The account isrestricted.

Check the user'sresources. Fordetails about theaccount restrictionreason, see MyAccount FAQ inHelp Center.

ModelArts.4107

Get user temp aksk error.

An exceptionoccurred whenobtaining thetemporaryAK/SK.

Contact HUAWEICLOUD supportpersonnel.

ModelArts.4201

Request url needservice id.

The requestURL does notcontain theservice ID.

Check the service IDin the request URL.

ModelArts.4202

Request url formatinvalid.

The requestURL format isinvalid.

Check the requestURL format.

ModelArts.4203

Access denied! Youdo not havepermission.

Accesspermission isunavailable.

Check the accesspermission.



https://support.huaweicloud.com/intl/en-us/account_faq/faq_bi_0002.html

https://support.huaweicloud.com/intl/en-us/account_faq/faq_bi_0002.html




Module

ErrorCode


ModelArts.4204

Access api error!Not subscribe thisapi.

The API hasnot beensubscribed.

Subscribe to theAPI. Rectify thefault by followingthe instructionsprovided in Why Isa Message Stating"ModelArts.4204"Displayed Whenthe OCR API IsCalled. If the APIhas been enabled,check whether theregion (or account)where the service isenabled is the sameas the region (oraccount) where theservice is called. Ifthey are the same,check whether theURL of the API iscorrect.

ModelArts.4601

The URL is notallowed.

The externalURL is invalid.

Check the format ofthe entereddownload address.

ModelArts.4603

Obtaining the filefrom the URLfailed.

The file failedto bedownloadedfrom theexternal URL.

Check the networkand URL.

ModelArts.4702

Query Obs agencyfailed.

The OBSagency failedto be queried.

Check whether theOBS agency hasbeen enabled forthe service.

ModelArts.4703

The Obs URL isinvalid.

The OBS URL isinvalid.

Check the OBS URL.

ModelArts.4704

Obtaining the filefrom the OBSfailed.

The OBS filefailed to beobtained.

Check the OBS file.

ModelArts.4705

The file stored onthe OBS isoversized.

The OBS file isoversized.

Check the size ofthe OBS file andensure that the filedoes not exceed thesize limit.









Module

ErrorCode


ModelArts.4706

The Obs file is notexist.

The OBS filedoes not exist.

Check whether thecorresponding fileexists.

APIG APIG.0101

The API does notexist or has notbeen published inthe environment.

The API doesnot exist or hasnot beenpublished.

Check whether theURL of the API iscorrect, whether theendpoint and thecorresponding URIare correct, whetherthe service isdeployed in thetarget region, andwhether the HTTPrequest method(such as POST andGET) is correct. Fordetails about theendpoint, seeEndpoints.For details aboutthe URI, see the APIpage of each API.

APIG.0201

Backend timeout. Request timedout.

Rectify the fault byfollowing theinstructionsprovided in Why Isa Message Stating"APIG.0201"Displayed Whenthe OCR API IsCalled.









Module

ErrorCode


APIG.0301

Incorrect IAMauthenticationinformation.

The IAMauthenticationinformation isincorrect.1. decrypt

token fail:The tokenfails to beparsed.

2. tokenexpires: Thetokenexpires.

3. verify aksksignaturefail: TheAK/SKauthentication fails.

1. If the token failsto be parsed,check themethod forobtaining thetoken, whetherthe request bodyis correct,whether thetoken is correct,and whether theenvironment forobtaining thetoken is thesame as theenvironment forcalling the token.

2. If the tokenexpires, obtain anew token that isvalidpermanently.

3. Check whetherthe AK/SK pair iscorrect. Forexample, the SKcorresponding tothe AK isincorrect; anextra space isentered in theAK/SK pair.

4. AK/SK-basedauthenticationerrors occurfrequently. If anAK/SK pair failsto beauthenticated formore than fiveconsecutivetimes, the AK/SKpair is locked for5 minutes (theAK/SK-basedauthentication isconsidered as anabnormal



Module

ErrorCode


authenticationrequest within 5minutes). After 5minutes, theAK/SK pair isunlocked and re-authenticated.

5. Check whetherthe account is inarrears or frozen.

APIG.0308

The throttlingthreshold has beenreached: policy useroverratelimit,limit:XX,time:1 minute.

The requestexceeds thedefault ratelimit of theservice.

Rectify the fault byfollowing theinstructionsprovided in Why Isa Message Stating"APIG.0308"Displayed Whenthe OCR API IsCalled.

Other

If other error codes are displayed, contact us.

5.3 Obtaining a Project ID

Obtaining a Project ID from the Management Console1. Log in to the management console.2. Hover the cursor over your username in the upper right corner and click My

Credentials from the drop-down list.3. On the My Credentials page, view the username and account name and view

projects in the project list.










https://console-intl.huaweicloud.com/console/?locale=en-us

Figure 5-1 Viewing the project ID

If there are multiple projects in one region, expand Region and viewsubproject IDs in the Project ID column.

Obtaining a Project ID by Calling an API

The API for obtaining a project ID is GET https://{endpoint}/v3/projects.{Endpoint} indicates the endpoint of IAM. For details about API authentication,see Authentication.

For example, if OCR is deployed in the ap-southeast-1 region, name is ap-southeast-1,, and id in projects is the project ID.{ "projects": [ { "domain_id": "65382450e8f64ac0870cd180d14e684b", "is_domain": false, "parent_id": "65382450e8f64ac0870cd180d14e684b", "name": "project_name", "description": "", "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22https://support-intl.huaweicloud.com/zh-cn/devg-apisign/api-sign-provide.htmlcd05f897d6b99" }, "id": "a4a5d4098fb4474fa22cd05f897d6b99", "enabled": true } ], "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects" } }

5.4 Obtaining an Account IDAn account ID (domain-id) is required for some URLs when an API is called. Toobtain an account ID, perform the following steps:

1. Log in to the management console after registration.2. Hover the cursor over your username and choose My Credentials.



On the My Credentials page, view the Account ID.

Figure 5-2 Viewing the account ID

5.5 Configuring Access Permissions of OBSMultimedia files such as images and audio files in the Enterprise Intelligence (EI)services can be directly processed by OBS. This reduces service usage costs,shortens service response time, and improves service experience.

To ensure data security, a service can used authorized URLs (https://<bucket-name>.<endpoint>/<object-name>) to access files stored on OBS after it isgranted with the required permission. Unauthorized services cannot obtain userdata. To obtain the user data in this case, enable public read authorization orprovide a URL that has been temporarily authorized.

Enabling Authorization for OCR

To use data in OBS, you need to enable OBS authorization. Go to the OCRhomepage and click Try Now to go to the OCR console. You need to have anaccount for logging in to the OCR console. Click Service Management. On thedisplayed page, click the OBS Authorization button to complete theauthorization. After the authorization is enabled, you can use the authorized URLto access the service.

Figure 5-3 OBS Authorization



https://www.huaweicloud.com/intl/en-us/product/ocr.html

NO TE

OBS must reside in the same region as OCR.

Enabling Public Read AuthorizationFor details about how to enable public read authorization, see Permission Controlin the Object Storage Service Console Operation Guide. Then, you can access thedata on OBS using the URL after the corresponding files are uploaded to OBS. TheURL can also serve as EI services' API request parameter for using related serviceAPIs.

Using Temporary Request AuthenticationPublic read authorization is easy to use. However, when it is enabled, sensitiveinformation, such as private data, may be disclosed. In this scenario, thetemporary authorization function provided by OBS comes in handy.

OBS allows users to construct a specific URL for objects in OBS. The URL containsauthentication information. Any user can use the URL to access the specifiedobject in OBS, but the URL is valid only before the expiry time specified in Expires.After a user issues temporary authorization, other users can perform operationswithout requiring the user's access key.

For details about how to use the OBS temporary authorization function, seesection "Authorized Access" in the Object Storage Service SDK Reference.Download the related SDK and sample code, and compile code to obtain therelated URL.



https://support.huaweicloud.com/intl/en-us/usermanual-obs/obs_03_0086.html

https://support.huaweicloud.com/intl/en-us/sdkreference-obs/obs_02_0001.html

A Change History

Release Date What's New

2020-11-25 Added the following content:Chile ID Card OCR

2019-07-23 Added the following content:Myanmar Driving License OCR

2019-04-29 This is the first official release.

Optical Character RecognitionAPI Reference A Change History


Date post:	30-Aug-2020
Category:	Documents
Upload:	others
View:	6 times
Download:	0 times

Optical Character Recognition - Huawei...Optical Character Recognition (OCR) allows you to detect...

Documents