Updated on 2024-06-19 GMT+08:00

ID Document

Function

This API detects and extracts text from images of identity documents and converts the text into a structured format. These documents include ID cards, driving licenses, and passports from multiple countries and regions. Table 1 lists the mapping between supported countries/regions and document types. For details about the constraints on using this API, see Constraints and Limitations. For details about how to use this API, see Introduction to OCR.

Table 1 Mapping between countries/regions and document types

Country/Region

Code

Document Type

Vietnam

VNM

PP, DL, and ID

India

IND

PP

Philippines

PHL

PP, DL, ID (UMID only)

Albania

ALB

PP, DL, and ID

Brazil

BRA

PP

Indonesia

IDN

PP

Malaysia

MYS

PP

Nigeria

NGA

PP

Pakistan

PAK

PP

Russia

RUS

PP (Only the international standard version is supported.)

Taiwan (China)

TWN

PP

Ukraine

UKR

PP

Thailand

THA

ID and PP

Chile

CHL

ID and PP

Hong Kong (China)

HKG

ID

  • PP: passport
  • DL: driving license
  • ID: identification card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

Constraints and Limitations

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

Calling Method

For details, see Calling APIs.

Prerequisites

Before using this API, subscribe to the service and complete authentication. For details, see Subscribing to an OCR Service and Authentication.

Before you use the service for the first time, subscribe to the service by clicking Subscribe. You only need to subscribe to the service once. If you have not subscribed to the service yet, error "ModelArts.4204" will be displayed when you call this API. Before you call the API, log in to the OCR console and subscribe to the corresponding service. Ensure that you make the subscription to the service in the same region where you want to call this API.

URI

POST /v2/{project_id}/ocr/id-document

Table 2 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 by referring to Obtaining a Project ID.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token

Used to obtain the permission to call 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 console, 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 will be categorized under the corresponding enterprise project for that ID.
  • If an enterprise project ID that is in the correct format but does not actually exist is carried, and the OCR service can be used properly, the bills will display the corresponding non-existent enterprise project ID.
  • If no enterprise project ID or an enterprise project ID with incorrect format (such as special characters) is carried, and the OCR service can be used properly, the bills will be categorized under default.
Table 4 Request body parameters

Parameter

Mandatory

Type

Description

image

No

String

Set 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 100 or larger than 8,192 pixels. Only images in JPEG, JPG, PNG, BMP, or TIFF format can be recognized.

url

No

String

Set either this parameter or image. Image URL. Currently, the following URLs are supported:

Image URL. Currently, the following URLs are supported:

  • Public 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.
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.

country_region

No

Array of strings

Code of the country or region where a certificate is issued. The code must be defined in ISO 3166-1 alpha-2 codes. This parameter is optional. You can enter one or more country/region codes. After this parameter is specified, the service identifies cards only in the specified country or region. If this parameter is left blank, all supported cards are identified. It is recommended that this field be filled in when the country/region is fixed or limited. For the list of supported countries and regions, see Table 1.

NOTE:

This parameter is mandatory when Vietnamese is recognized.

id_type

No

Array of strings

Document type. This parameter is optional. One or more types of documents are supported. If this parameter is specified, the service identifies only the documents of the specified type. If this parameter is left blank, all types of documents are identified by default. You are advised to configure this parameter if the document type is known. The following document types are supported:

  • PP: passport
  • DL: driving license
  • ID: identity card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

return_portrait_image

No

Boolean

Whether to return the portrait image (face image in the document). The value true indicates that the portrait image needs to be returned, and the value false indicates that the portrait image does not need to be returned.

Response Parameters

Status code: 200

Table 5 Response body parameter

Parameter

Type

Description

result

IdDocumentItem object

Recognition result

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

Table 6 IdDocumentItem

Parameter

Type

Description

country_region

String

Code of the country or region where a certificate is issued. The code must be defined in ISO 3166-1 alpha-2 codes. For the list of supported countries and regions, see Table 1.

id_type

String

Document type. The options are:

  • PP: passport
  • DL: driving license
  • ID: identity card, which is an identity card issued by a country or region, such as an ID card, voter registration card, and social security card.

side

String

Front or back of an identity document. The options are:

  • front: front side of the document, which is typically the side that contains a portrait.
  • back: front is returned if a document has only one side.

first_name

String

First name

last_name

String

Last name

sex

String

Gender. The options are: M: male; F: female; X: third gender.

nationality

String

Nationality of the document holder

birth_date

String

Date of birth, in YYYY-MM-DD format

issue_date

String

Date of issue, in YYYY-MM-DD format

expiry_date

String

Expiration date, in YYYY-MM-DD format

document_number

String

Document number

address

String

Contact address of the holder

issuing_authority

String

Issuing authority

portrait_image

String

Base64 encoded string of the portrait on the document, which is optional

confidence

Object

Field confidence. The value is a decimal ranging from 0 to 1. A larger value indicates more reliable recognition results.

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 returned for a successful call.

error_msg

String

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

Example Request

  • endpoint is the request URL for calling an API. Endpoints vary depending on services and regions. For details, see Endpoints.

    For example, ID Document OCR is deployed in the CN-Hong Kong region. The endpoint is ocr.ap-southeast-1.myhuaweicloud.com or ocr.ap-southeast-1.myhuaweicloud.cn. The request URL is https://ocr.ap-southeast-1.myhuaweicloud.com/v2/{project_id}/ocr/id-document. project_id is the project ID. For how to obtain the project ID, see Obtaining a Project ID.

  • For details about how to obtain a token, see Making an API Request.
  • Request example (Method 1: Use the image Base64 string.)
    POST https://{endpoint}/v2/{project_id}/ocr/id-document
    
    {
      "image" : "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...",
      "country_region" : "ALB",
      "id_type" : "PP"
    }
  • Request example (Method 2: Use the image URL.)
    POST https://{endpoint}/v2/{project_id}/ocr/id-document
    
    {
      "url" : "https://BucketName.obs.xxxx.com/ObjectName",
      "country_region" : "ALB",
      "id_type" : "PP"
    }

Example Response

Status code: 200

Example response for a successful request

{
  "result" : {
    "country_region" : "ALB",
    "id_type" : "PP",
    "side" : "front"
  }
}

Status code: 400

Example response for a failed request

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

Example SDK Code

The example SDK code is as follows:

You are advised to update the SDKs to the latest versions before use to prevent the local outdated SDKs from being unable to use the latest OCR functions.

  • Transfer the Base64 encoded string of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.ocr.v1.region.OcrRegion;
    import com.huaweicloud.sdk.ocr.v1.*;
    import com.huaweicloud.sdk.ocr.v1.model.*;
    
    import java.util.List;
    import java.util.ArrayList;
    
    public class RecognizeIdDocumentSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
    
            ICredential auth = new BasicCredentials()
                    .withAk(ak)
                    .withSk(sk);
    
            OcrClient client = OcrClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(OcrRegion.valueOf("<YOUR REGION>"))
                    .build();
            RecognizeIdDocumentRequest request = new RecognizeIdDocumentRequest();
            IdDocumentRequestBody body = new IdDocumentRequestBody();
            List<String> listbodyIdType = new ArrayList<>();
            listbodyIdType.add("PP");
            List<String> listbodyCountryRegion = new ArrayList<>();
            listbodyCountryRegion.add("ALB");
            body.withIdType(listbodyIdType);
            body.withCountryRegion(listbodyCountryRegion);
            body.withImage("/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...");
            request.withBody(body);
            try {
                RecognizeIdDocumentResponse response = client.recognizeIdDocument(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Transfer the URL of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    package com.huaweicloud.sdk.test;
    
    import com.huaweicloud.sdk.core.auth.ICredential;
    import com.huaweicloud.sdk.core.auth.BasicCredentials;
    import com.huaweicloud.sdk.core.exception.ConnectionException;
    import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
    import com.huaweicloud.sdk.core.exception.ServiceResponseException;
    import com.huaweicloud.sdk.ocr.v1.region.OcrRegion;
    import com.huaweicloud.sdk.ocr.v1.*;
    import com.huaweicloud.sdk.ocr.v1.model.*;
    
    import java.util.List;
    import java.util.ArrayList;
    
    public class RecognizeIdDocumentSolution {
    
        public static void main(String[] args) {
            // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
            // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
            String ak = System.getenv("CLOUD_SDK_AK");
            String sk = System.getenv("CLOUD_SDK_SK");
    
            ICredential auth = new BasicCredentials()
                    .withAk(ak)
                    .withSk(sk);
    
            OcrClient client = OcrClient.newBuilder()
                    .withCredential(auth)
                    .withRegion(OcrRegion.valueOf("<YOUR REGION>"))
                    .build();
            RecognizeIdDocumentRequest request = new RecognizeIdDocumentRequest();
            IdDocumentRequestBody body = new IdDocumentRequestBody();
            List<String> listbodyIdType = new ArrayList<>();
            listbodyIdType.add("PP");
            List<String> listbodyCountryRegion = new ArrayList<>();
            listbodyCountryRegion.add("ALB");
            body.withIdType(listbodyIdType);
            body.withCountryRegion(listbodyCountryRegion);
            body.withUrl("https://BucketName.obs.xxxx.com/ObjectName");
            request.withBody(body);
            try {
                RecognizeIdDocumentResponse response = client.recognizeIdDocument(request);
                System.out.println(response.toString());
            } catch (ConnectionException e) {
                e.printStackTrace();
            } catch (RequestTimeoutException e) {
                e.printStackTrace();
            } catch (ServiceResponseException e) {
                e.printStackTrace();
                System.out.println(e.getHttpStatusCode());
                System.out.println(e.getRequestId());
                System.out.println(e.getErrorCode());
                System.out.println(e.getErrorMsg());
            }
        }
    }
    
  • Transfer the Base64 encoded string of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    # coding: utf-8
    
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkocr.v1.region.ocr_region import OcrRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkocr.v1 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.getenv("CLOUD_SDK_AK")
        sk = os.getenv("CLOUD_SDK_SK")
    
        credentials = BasicCredentials(ak, sk) \
    
        client = OcrClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(OcrRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = RecognizeIdDocumentRequest()
            listIdTypebody = [
                "PP"
            ]
            listCountryRegionbody = [
                "ALB"
            ]
            request.body = IdDocumentRequestBody(
                id_type=listIdTypebody,
                country_region=listCountryRegionbody,
                image="/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA..."
            )
            response = client.recognize_id_document(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Transfer the URL of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    # coding: utf-8
    
    from huaweicloudsdkcore.auth.credentials import BasicCredentials
    from huaweicloudsdkocr.v1.region.ocr_region import OcrRegion
    from huaweicloudsdkcore.exceptions import exceptions
    from huaweicloudsdkocr.v1 import *
    
    if __name__ == "__main__":
        # The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        # In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak = os.getenv("CLOUD_SDK_AK")
        sk = os.getenv("CLOUD_SDK_SK")
    
        credentials = BasicCredentials(ak, sk) \
    
        client = OcrClient.new_builder() \
            .with_credentials(credentials) \
            .with_region(OcrRegion.value_of("<YOUR REGION>")) \
            .build()
    
        try:
            request = RecognizeIdDocumentRequest()
            listIdTypebody = [
                "PP"
            ]
            listCountryRegionbody = [
                "ALB"
            ]
            request.body = IdDocumentRequestBody(
                id_type=listIdTypebody,
                country_region=listCountryRegionbody,
                url="https://BucketName.obs.xxxx.com/ObjectName"
            )
            response = client.recognize_id_document(request)
            print(response)
        except exceptions.ClientRequestException as e:
            print(e.status_code)
            print(e.request_id)
            print(e.error_code)
            print(e.error_msg)
    
  • Transfer the Base64 encoded string of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        ocr "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            Build()
    
        client := ocr.NewOcrClient(
            ocr.OcrClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.RecognizeIdDocumentRequest{}
    	var listIdTypebody = []string{
            "PP",
        }
    	var listCountryRegionbody = []string{
            "ALB",
        }
    	imageIdDocumentRequestBody:= "/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA..."
    	request.Body = &model.IdDocumentRequestBody{
    		IdType: &listIdTypebody,
    		CountryRegion: &listCountryRegionbody,
    		Image: &imageIdDocumentRequestBody,
    	}
    	response, err := client.RecognizeIdDocument(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    
  • Transfer the URL of the certificate image for recognition.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    package main
    
    import (
    	"fmt"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/core/auth/basic"
        ocr "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1"
    	"github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/model"
        region "github.com/huaweicloud/huaweicloud-sdk-go-v3/services/ocr/v1/region"
    )
    
    func main() {
        // The AK and SK used for authentication are hard-coded or stored in plaintext, which has great security risks. It is recommended that the AK and SK be stored in ciphertext in configuration files or environment variables and decrypted during use to ensure security.
        // In this example, AK and SK are stored in environment variables for authentication. Before running this example, set environment variables CLOUD_SDK_AK and CLOUD_SDK_SK in the local environment
        ak := os.Getenv("CLOUD_SDK_AK")
        sk := os.Getenv("CLOUD_SDK_SK")
    
        auth := basic.NewCredentialsBuilder().
            WithAk(ak).
            WithSk(sk).
            Build()
    
        client := ocr.NewOcrClient(
            ocr.OcrClientBuilder().
                WithRegion(region.ValueOf("<YOUR REGION>")).
                WithCredential(auth).
                Build())
    
        request := &model.RecognizeIdDocumentRequest{}
    	var listIdTypebody = []string{
            "PP",
        }
    	var listCountryRegionbody = []string{
            "ALB",
        }
    	urlIdDocumentRequestBody:= "https://BucketName.obs.xxxx.com/ObjectName"
    	request.Body = &model.IdDocumentRequestBody{
    		IdType: &listIdTypebody,
    		CountryRegion: &listCountryRegionbody,
    		Url: &urlIdDocumentRequestBody,
    	}
    	response, err := client.RecognizeIdDocument(request)
    	if err == nil {
            fmt.Printf("%+v\n", response)
        } else {
            fmt.Println(err)
        }
    }
    

For more SDK code examples in various programming languages, see the Sample Code tab on the right of the API Explorer page, which can automatically generate corresponding SDK code examples.

Status Codes

Status Code

Description

200

Example response for a successful request

400

Example response for a failed request

See Status Codes.

Error Codes

See Error Codes.