Help Center> Optical Character Recognition> API Reference> APIs> Mainland Travel Permit for Hong Kong, Macao, and Taiwan Residents
Updated on 2022-11-30 GMT+08:00

Mainland Travel Permit for Hong Kong, Macao, and Taiwan Residents

Function

This API identifies and extracts text from images of mainland travel permits and converts the text into a structured format. This OCR service supports the following two types of mainland travel permits: mainland travel permit for Hong Kong and Macao residents and mainland travel permit for Taiwan residents. 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, 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 Mainland Travel Permit for Hong Kong, Macao, and Taiwan Residents 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.

URI

POST https://{endpoint}/v2/{project_id}/ocr/mainland-travel-permit

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 data. No side of the image can be smaller than 15 or larger than 8,192 pixels. Only images in 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.

return_portrait_image

No

Boolean

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

  • true: The Base64 code of the portrait on the travel permit will be returned.
  • false: The Base64 code of the portrait on the travel permit 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 travel permit will not be returned.

return_portrait_location

No

Boolean

Whether to return the location of the portrait on the travel permit. Value options are as follows:

  • true: The location of the portrait on the travel permit will be returned.
  • false: The location of the portrait on the travel permit will not be returned.

If this parameter is not specified, false is used by default. In this case, the location of the portrait on the travel permit will not be returned.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

result

MainlandTravelPermitResult object

Calling result of a successful API call

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

Table 5 MainlandTravelPermitResult

Parameter

Type

Description

name

String

Chinese name

name_en

String

Name in English

birth_date

String

Date of birth

sex

String

Gender

valid_period

String

Date of expiry

issuing_authority

String

Issuing authority

number

String

Permit number

issue_place

String

Place where the permit is issued

issue_times

String

Number of issuing times

id_name

String

ID card name on the back side of the permit

id_number

String

ID card number on the back side of the permit

machine_code1

String

Machine-readable code in the first line

machine_code2

String

Machine-readable code in the second line

machine_code3

String

Machine-readable code in the third line

type

String

Permit type. Value options are as follows:

  • Mainland Travel Permit for Hong Kong and Macao Residents
  • Mainland Travel Permit for Taiwan Residents

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

portrait_image

String

Base64 code of the portrait. This parameter is available only when return_portrait_image is set to true.

portrait_location

Array<Array<Integer>>

Location of the portrait on the original image. This parameter is available only when return_portrait_location is set to true. The image is displayed in a list. The list contains the two-dimensional coordinates (x,y) of the four vertices in the portrait area. The origin of the coordinates is the upper left corner of the image. The x axis is horizontal, and the y axis is vertical.

confidence

MainlandTravelPermitConfidence object

Confidence of each field

Table 6 MainlandTravelPermitConfidence

Parameter

Type

Description

name

Float

Confidence of the Chinese name

name_en

Float

Confidence of the English name

birth_date

Float

Confidence of the birth date

sex

Float

Confidence of the gender

valid_period

Float

Confidence of the validity period

issuing_authority

Float

Confidence of the issuing authority

number

Float

Confidence of the permit number

issue_place

Float

Confidence of the place of issuance

issue_times

Float

Confidence of the number of issuing times

type

Float

Confidence of the permit type

side

Float

Confidence of information on the front and back sides of image of the permit

id_name

Float

Confidence of the ID card name on the back side of the permit

id_number

Float

Confidence of the ID number on the back side of the permit

machine_code1

Float

Confidence of the machine-readable code in the first line

machine_code2

Float

Confidence of the machine-readable code in the second line

machine_code3

Float

Confidence of the machine-readable code in the third line

Status code: 400

Table 7 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/mainland-travel-permit
    Request Header:
    Content-Type: application/json,
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG... 
    Request Body:
    {
        "image": "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgA..."
        "return_portrait_image": True,
        "return_portrait_location": True
    }
  • Request example (Method 2: Use the image URL.)
    POST  https://{endpoint}/v2/{project_id}/ocr/mainland-travel-permit
    Request Header:
    Content-Type: application/json,
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG... 
    Request Body:
    {
        "url": "https://BucketName.obs.xxxx.com/ObjectName",
        "return_portrait_image": True,
        "return_portrait_location": True
    }

Example Responses

Status code: 200

Example of a successful response

{
  "result" : {
    "name": "Zhang San",
    "name_en" : "ZHANG, SAN",
    "birth_date" : "1992.10.11",
    "sex": "M",
    "valid_period" : "1992.10.11-2002.04.04",
    "issuing_authority": "Bureau of Exit and Entry Administration of the Ministry of Public Security",
    "number" : "E23xxxxxx",
    "issue_times" : "00",
    "type": "Mainland Travel Permit for Hong Kong and Macao Residents",
    "side" : "front",
    "confidence" : {
      "name" : 0.9999,
      "name_en" : 0.9868,
      "birth_date" : 0.9984,
      "sex" : 0.9999,
      "valid_period" : 0.9988,
      "issuing_authority" : 0.9998,
      "number" : 0.9999,
      "issue_times" : 0.9997,
      "type" : 0.9999,
      "side" : 1.0
    }
  }
}

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.