Help Center> Optical Character Recognition> API Reference> APIs> Macao Resident ID Card
Updated on 2022-11-30 GMT+08:00
View PDF

Macao Resident ID Card

Function

This API identifies and extracts text from images of Macao-issued resident ID cards and converts the text into a structured format. For details about the constraints on using this API, see Constraints. For details about how to use this API, see Introduction to OCR.

Constraints

  • Only images in PNG, JPG, JPEG, BMP, or TIFF format can be recognized.
  • No side of the image can be smaller than 15 or larger than 8,192 pixels.
  • An ID card to be recognized must occupy more than 50% of the image. When scanning an ID card, ensure that the entire ID card is displayed in the image.
  • Images can be rotated horizontally to any angle, but the recognition precision is affected.
  • Illuminated or dark images can be recognized, but the accuracy may be compromised.

Prerequisites

Before using Macao Resident ID Card OCR, you need to apply for the service and complete authentication. For details, see Subscribing to an OCR Service and Authentication.

Before using the service for the first time, you need to enable the service by clicking Subscribe. You only need to subscribe to the service once. If the service is not enabled, an error message with error code "ModelArts.4204" will be displayed when you call the service. Before calling the service, log in to the OCR console and enable the service. Ensure that the region where the service is enabled is the same as that where the service is called.

Debugging

You can debug this API through automatic authentication in API Explorer. API Explorer can automatically generate and debug sample SDK code.

API Explorer can be called in ap-southeast-1.

URI

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

Table 1 URI parameters

Parameter

Mandatory

Description

endpoint

Yes

Endpoint, which is the request address for calling an API.

The endpoint varies depending on services in different regions. For more details, see Endpoints.

project_id

Yes

Project ID, which can be obtained from Obtaining a Project ID.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

Used to obtain the permission to operate APIs. The token is the value of X-Subject-Token in the response header in Authentication.

Content-Type

Yes

String

MIME type of the request body. The value is application/json.

Enterprise-Project-Id

No

String

Enterprise project ID. OCR uses Enterprise Project Management Service (EPS) to split fees for resources used by different user groups and users.

To obtain the enterprise project ID, go to the Enterprise Project Management page, click the enterprise project name, and obtain the enterprise project ID on the enterprise project details page.

For details about how to create an enterprise project, see Optical Character Recognition User Guide.

NOTE:

After an enterprise project is created, parameter transfer involves the following scenarios:

  • If a correct enterprise project ID is carried and the OCR service can be used properly, the bills are allocated to the enterprise project corresponding to the ID.
  • If an incorrect enterprise project ID is carried and the OCR service can be used properly, the enterprise project in the bills is allocated to Non-project.
  • If no enterprise project ID is carried and the OCR service can be used properly, the enterprise project in the bills is allocated to Non-project.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

image

No

String

Configure either this parameter or url.

Base64-encoded image file. The image file has a size limit of 10 MB.

No side of the image can be smaller than 15 or larger than 8,192 pixels. Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.

An example is /9j/4AAQSkZJRgABAg.... If the image data contains an unnecessary prefix, the error "The image format is not supported" is reported.

url

No

String

Configure either this parameter or image.

Image URL. Currently, the following URLs 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, and anonymous public authorization. For details, see Configuring Access Permissions of OBS.
NOTE:
  • The API response time depends on the image download time. If the image download takes a long time, the API call will fail.
  • Ensure that the storage service where the image to be detected resides is stable and reliable. OBS is recommended for storing image data.

side

No

String

front: front of an ID card

back: back of an ID card

If this parameter is left empty or not included, the system automatically recognizes whether the image is the front or back of an ID card. To ensure accuracy, set this parameter.

return_portrait_image

No

Boolean

Whether to return the portrait. Value options are as follows:

  • true: The Base64 code of the portrait on the ID card will be returned.
  • false: The Base64 code of the portrait on the ID card will not be returned.

If this parameter is not specified, false is used by default. In this case, the Base64 code of the portrait on the ID card will not be returned.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

result

MacaoIdCardResult object

Calling result of a successful API call

This parameter is not included when the API fails to be called.
Table 5 MacaoIdCardResult

Parameter

Type

Description

side

String

Whether the front or back side of the ID card is displayed. Value options are as follows:

  • front: front side
  • back: back side

name

String

Name

name_en

String

Name in English. Words in the name are separated by spaces.

sex

String

Gender. Value options are M and F. M indicates male and F indicates female.

issue_date

String

Date of issue

expiry_date

String

Date of expiry

birth_date

String

Date of birth

initial_issue_date

String

Date of first issue

height

String

Height

number

String

ID card number

symbols

String

Code for place of birth and gender

machine_code1

String

Machine-readable code in the first line on the back of an ID card

machine_code2

String

Machine-readable code in the second line on the back of an ID card

machine_code3

String

Machine-readable code in the third line on the back of an ID card

portrait_image

String

Base64 code of the head portrait on the ID card. If the input parameter return_portrait_image is missing, this parameter does not exist.

confidence

Object

Confidence of related fields. A higher confidence indicates a higher accuracy of the field identified. The confidence is calculated using algorithms and is not equal to the accuracy.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Error code of a failed API call. For details, see Error Codes. This parameter is not included when the API is successfully called.

error_msg

String

Error message when the API call fails. This parameter is not included when the API is successfully called.

Example Requests

  • Request example (Method 1: Use the image Base64 string.)
    POST https://{endpoint}/v2/{project_id}/ocr/macao-id-card
Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body:
{ 
    "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...", 
    "side": "front",
    "return_portrait_image": "false"
 }
  • Request example (Method 2: Use the image URL.)
    POST https://{endpoint}/v2/{project_id}/ocr/macao-id-card
Request Header:
Content-Type: application/json
X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
Request Body:
{ 
    "url":"https://BucketName.obs.myhwclouds.com/ObjectName", 
    "side": "front",
    "return_portrait_image": "false"
 }

Example Responses

Status code: 200

Example of a successful response

{
  "result" : {
    "id_number" : "784-1995-xxxxxxx-4",
    "name": "Zhang San",
    "name_en" : "ZHANG, SAN",
    "birth_date" : "08-08-1980",
    "sex" : "M",
    "issue_date" : "08-08-2012",
    "expiry_date" : "08-08-2022",
    "initial_issue_date" : "18-02-2000",
    "height" : "166",
    "symbols" : "AS",
    "confidence" : {
      "id_number" : 0.9234,
      "name" : 0.9234,
      "name_en" : 0.9234,
      "birth_date" : 0.9234,
      "sex" : 0.9234,
      "issue_date" : 0.9234,
      "expiry_date" : 0.9234,
      "initial_issue_date" : 0.9234,
      "height" : 0.9234,
      "symbols" : 0.9234
    }
  }
}

Status code: 400

Example of a failed response

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

Status Codes

Status Code

Description

200

Success response

400

Failure response

For details about status codes, see Status Codes.

Error Codes

For details about error codes, see Error Codes.

Parent topic: APIs