Help Center > > API Reference> API> Passport OCR

Passport OCR

Updated at: Aug 05, 2019 GMT+08:00

Function

Passport OCR recognizes the structured information on the first page of passports.

Passport OCR can recognize all fields on a Chinese passport. A foreign passport can be identified by the machine-readable code at the bottom of the passport with 6 to 7 key fields extracted from the code.

URI

URI format:

POST /v1.0/ocr/passport

Request Message

Table 1 describes the request parameters of Passport OCR.
Table 1 Request parameters

Parameter

Mandatory

Type

Description

image

Configure either this parameter or url.

String

Base64 character string converted from the image. The size cannot exceed 10 MB.

The narrow edge contains at least 15 pixels and the wide edge contains at most 4096 pixels. The JPG, PNG, BMP, and TIFF formats are supported.

url

Configure either this parameter or image.

String

URL of the image file. Currently, URLs for anonymously and publicly authorized or external access to image files stored on OBS are supported.

country_code

No

String

Country code on the passport. The recognition mode is determined based on the country code.

  • If this parameter is left blank, OCR automatically matches the recognition mode based on the passport type identified by the service.
  • If you set this parameter to GENERAL, the passport is recognized based on the machine-readable code.
  • If this parameter is set to CHN, all fields in the Chinese passport are recognized.

Response Message

Table 2 describes the response parameters of Passport OCR.
Table 2 Response parameters

Parameter

Type

Description

error_code

String

Error code when the API fails to be called. For details, see Error Code.

This parameter is not included when the API is successfully called.

error_msg

String

Error message when the API fails to be called.

This parameter is not included when the API is successfully called.

result

JSON

Calling result when the API is successfully called.

result consists of the following three parts: 13 key fields, expressed in English; extra_info, passport information in the local official language; and confidence, confidence scores of key fields. A higher confidence score indicates a more accurate result.

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

passport_type

String

Passport type (in English). P indicates a common private passport. W indicates a diplomatic passport. G indicates a business passport.

country_code

String

Country code, in English

passport_number

String

Passport number, in English

nationality

String

Nationality of a passport holder, in English

surname

String

Surname, in English

given_name

String

Given name, in English

sex

String

Gender, in English

date_of_birth

String

Date of birth, in English

date_of_expiry

String

Date of expiry, in English

date_of_issue

String

Date of issue, in English

place_of_birth

String

Place of birth, in English

place_of_issue

String

Place of issue, in English

issuing_authority

String

Authority, in English, where the abbreviation of China is P.R.China

confidence

JSON

Confidence scores of related fields. A higher confidence score indicates a more accurate result. Note that the confidence scores are provided by the algorithm and are not equal to the accuracy of the fields.

extra_info

JSON

By default, this parameter is left blank. For the OCR service for passports in some common countries, extra_info contains field information and other information described in the local official language on passports.

For example, for Chinese passports, extra_info contains the name and place of birth in Chinese.

Example

  • Request example: Use a Base64-encoded image.
    POST https://{endpoint}/v1.0/ocr/passport
     
    Request Header:
    Content-Type: application/json
    X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDTALBglghkgBZQMEAgEwgguVBgkqhkiG...
    Request Body:
    {
        "image":"/9j/4AAQSkZJRgABAgEASABIAAD/4RFZRXhpZgAATU0AKgAAAA...",
        "country_code": "GENERAL"
    }
  • Response example
    • Example 1: Chinese passport
      {
          "result": {
              "passport_type": "P", 
              "country_code": "CHN", 
              "passport_number": "ED9996060", 
              "nationality": "CHINESE", 
              "surname": "HU", 
              "given_name": "ZHAO", 
              "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": "胡照", 
                      "sex": "女", 
                      "place_of_birth": "湖南", 
                      "place_of_issue": "广东", 
                      "issuing_authority": "公安部出入境管理局", 
                      "nationality": "中国"
                  }
              }, 
              "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": "EP4350000", 
              "date_of_birth": "1985-09-18", 
              "sex": "M", 
              "date_of_expiry": "2022-01-15", 
              "machine_code": "P<ETFHUZHAO<< ZHAOMIN <DESALEGN<<<<<<<<<<<<<<<", 
              "machine_code2": "EP43500007ETF8509185M2201155<<<<<<<<<<<<<<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
              }
          }
      }
  • Failed response example
    {
        "error_code": "AIS.0103", 
        "error_msg": "The image size does not meet the requirements" 
    }

Status Code

For details about the status code, see Status Code.

Did you find this page helpful?

Submit successfully!

Thank you for your feedback. Your feedback helps make our documentation better.

Failed to submit the feedback. Please try again later.

Which of the following issues have you encountered?







Please complete at least one feedback item.

Content most length 200 character

Content is empty.

OK Cancel