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.

        
         
           
           
             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.

        
         
           
           
             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.

        
         
           
           
             # 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.

        
         
           
           
             # 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.

        
         
           
           
             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.

        
         
           
           
             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.