/ocr/parse_idcard_ocr_result

优质

小牛编辑

137浏览

2023-12-01

1.接口描述

对APP端身份证的OCR扫描结果进行解析，并返回解析结果，本接口需要配合APP端SDK使用。

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result

2.请求参数

字段	类型	必需	描述
api_id	string	是	API 账户
api_secret	string	是	API 密钥
file	file	是	APP端银行卡或身份证OCR识别结果文件
return_image	string	否	默认为`false`, 不返回原图

3.返回参数

字段	类型	说明
status	string	返回状态，正常为 `OK`，其他值表示失败，详见错误码
valid	string	识别结果是否全部有效，是为`1`, 否为`0`
type	string	身份证类型，未知为`0`，正常身份证为`1`，临时身份证为`2`，预留为`3`
orient	string	身份证旋转方向信息，未知为`0`，身份证向上为`1`，身份证向左为`2`，身份证向下为`3`，身份证向右为`4`
side	string	身份证正背面信息，未知为`0`，身份证正面为`1`，身份证背面为`2`
corners	string	检测到身份证的四个角点坐标：左上、右上、左下、右下
info	string	信息条目数组，详见`info`数组中字段的结构
quality_score	string	身份证有效信息得分
image_crop	string	卡片类型
code	string	公有云返回码
version	string	版本
request_id	string	请求id

info数组中字段的结构为：

字段	类型	说明
name	string	姓名，详见信息条目的字段结构
sex	string	性别，详见信息条目的字段结构
nation	string	民族，详见信息条目的字段结构
year	string	出生年，详见信息条目的字段结构
month	string	出生月，详见信息条目的字段结构
day	string	出生日，详见信息条目的字段结构
address	string	地址，详见信息条目的字段结构
idNum	string	身份证号，详见信息条目的字段结构
authority	string	签发机关，详见信息条目的字段结构
validity	string	身份证有效期，详见信息条目数组中字段的结构

上传身份证正面照片时返回字段name,sex,nation,year,mouth,day,address和idNum，上传身份证背面照片时返回字段authority和validity。

信息条目数组中字段的结构：

字段	类型	说明
valid	boolean	该信息条目识别结果是否有效，是为`1`, 否为`0`
keyword_region	string	该信息条目的类别文字（即`姓名`、`性别`、`年`等文字）在输出图片中的位置(矩形的左上角和右下角坐标), [left, top, right, bottom]
text_region	string	该信息条目的信息内容文字在输出图片中的位置(矩形的左上角和右下角坐标), [left, top, right, bottom]
text	string	该信息条目的信息内容

返回结果示例：

{
  "status": "OK",
  "valid": 1,
  "type": 1,
  "orient": 1,
  "side": 1,
  "corners": [
    {
      "x": 84.01576232910156,
      "y": 105.88507080078125
    },
    {
      "x": 972.3495483398438,
      "y": 103.5886459350586
    },
    {
      "x": 88.88505554199219,
      "y": 661.0738525390625
    },
    {
      "x": 973.4779052734375,
      "y": 651.9923095703125
    }
  ],
  "info": {
    "name": {
      "valid": 1,
      "keyword_region": {
        "left": 86,
        "top": 110,
        "right": 188,
        "bottom": 147
      },
      "text_region": {
        "left": 223,
        "top": 91,
        "right": 407,
        "bottom": 154
      },
      "text": "老王"
    },
    "sex": {
      "valid": 1,
      "keyword_region": {
        "left": 85,
        "top": 209,
        "right": 189,
        "bottom": 247
      },
      "text_region": {
        "left": 222,
        "top": 206,
        "right": 300,
        "bottom": 257
      },
      "text": "男"
    },
    "nation": {
      "valid": 1,
      "keyword_region": {
        "left": 375,
        "top": 209,
        "right": 479,
        "bottom": 247
      },
      "text_region": {
        "left": 481,
        "top": 207,
        "right": 563,
        "bottom": 257
      },
      "text": "汉"
    },
    "year": {
      "valid": 1,
      "keyword_region": {
        "left": 88,
        "top": 309,
        "right": 190,
        "bottom": 346
      },
      "text_region": {
        "left": 218,
        "top": 304,
        "right": 354,
        "bottom": 350
      },
      "text": "19xx"
    },
    "month": {
      "valid": 1,
      "keyword_region": {
        "left": 88,
        "top": 309,
        "right": 190,
        "bottom": 346
      },
      "text_region": {
        "left": 424,
        "top": 304,
        "right": 488,
        "bottom": 350
      },
      "text": "x"
    },
    "day": {
      "valid": 1,
      "keyword_region": {
        "left": 88,
        "top": 309,
        "right": 190,
        "bottom": 346
      },
      "text_region": {
        "left": 536,
        "top": 304,
        "right": 622,
        "bottom": 350
      },
      "text": "xx"
    },
    "address": {
      "valid": 1,
      "keyword_region": {
        "left": 86,
        "top": 416,
        "right": 191,
        "bottom": 453
      },
      "text_region": {
        "left": 217,
        "top": 409,
        "right": 769,
        "bottom": 527
      },
      "text": "北京市xxxxxxxxxxxxxxxxxxx"
    },
    "idNum": {
      "valid": 1,
      "keyword_region": {
        "left": 86,
        "top": 678,
        "right": 373,
        "bottom": 718
      },
      "text_region": {
        "left": 414,
        "top": 672,
        "right": 1169,
        "bottom": 727
      },
      "text": "1306xxxxxxxxxxx4814"
    },
    "authority": {
      "valid": 0,
      "keyword_region": {
        "left": 0,
        "top": 0,
        "right": 0,
        "bottom": 0
      },
      "text_region": {
        "left": 0,
        "top": 0,
        "right": 0,
        "bottom": 0
      },
      "text": "x"
    },
    "validity": {
      "valid": 0,
      "keyword_region": {
        "left": 0,
        "top": 0,
        "right": 0,
        "bottom": 0
      },
      "text_region": {
        "left": 0,
        "top": 0,
        "right": 0,
        "bottom": 0
      },
      "text": "x"
    }
  },
  "quality_score": 0.800000011920929,
  "image_crop": "...", //如果return_image设置为true，此处会返回图片的base64编码值
  "code": 1000,
  "version": "0.1.0",
  "request_id": "TID05239a8208cd43f6bf89dc9df6074223"
}

4.错误码

状态码	`status` 字段	说明
`400`	ENCODING_ERROR	参数非UTF-8编码
`400`	INVALID_ARGUMENT	请求参数错误，具体原因见 `reason` 字段内容
`400`	PARSE_IDCARD_ERROR	上传的加密文件有误
`400`	SAVE_IDCARD_IMG_ERROR	存储图片错误
`401`	UNAUTHORIZED	账号或密钥错误
`401`	KEY_EXPIRED	账号过期，具体情况见 `reason` 字段内容
`403`	RATE_LIMIT_EXCEEDED	调用频率超出限额
`403`	NO_PERMISSION	无调用权限
`403`	OUT_OF_QUOTA	调用次数超出限额
`404`	NOT_FOUND	请求路径错误
`500`	INTERNAL_ERROR	服务器内部错误

5.输入示例

cURL 样例

curl -X POST "https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result?api_id=ID&api_secret=SECRET" \
  -F file=@/PATH/TO/OCR_FILE

HTTPie 样例

http -f POST "https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result?api_id=ID&api_secret=SECRET" \
  file=@/PATH/TO/OCR_FILE

C++ 样例

#include <iostream>
#include <cstring>
#include <exception>
#include <curl/curl.h>
#include <json/json.h>

using namespace std;
size_t callback(char *ptr, size_t size, size_t nmemb, string &stream){

  size_t sizes = size*nmemb;
  string temp(ptr,sizes);
  stream += temp;
  return sizes;
}
int main( int argv, char * argc[] ){

  CURL *curl;
  CURLM *multi_handle;
  CURLcode res;
  long code;
  string stream;
  struct curl_httppost *formpost = NULL;
  struct curl_httppost *lastptr = NULL;
  struct curl_slist *headerlist = NULL;

  try{

    curl_global_init(CURL_GLOBAL_DEFAULT);
    curl = curl_easy_init();

    if( curl ){

      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"api_id",
                  CURLFORM_COPYCONTENTS, "ID",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"api_secret",
                  CURLFORM_COPYCONTENTS, "SECRET",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"type",
                  CURLFORM_COPYCONTENTS, "TYPE",CURLFORM_END);
      curl_formadd(&formpost,&lastptr,CURLFORM_COPYNAME,"file",
                  CURLFORM_FILE, argc[1], CURLFORM_END);

      curl_easy_setopt(curl, CURLOPT_URL, "https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result");
      curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost);
      curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, callback);
      curl_easy_setopt(curl, CURLOPT_WRITEDATA, &stream);

      #ifdef SKIP_PEER_VERIFICATION
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
      #endif
      #ifdef SKIP_HOSTNAME_VERIFICATION
        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
      #endif

      res = curl_easy_perform(curl);

      if( res != CURLE_OK ){
        cout<<"curl_easy_perform() failed:"<<curl_easy_strerror(res)<<endl;
        return -1;
      }
      curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &code);
      Json::Value res_data;
      Json::Reader *reader = new Json::Reader(Json::Features::strictMode());
      if(!reader->parse(stream, res_data)){
        cout<<"parse error";
        return -1;
      }
      cout<<"HTTP Status Code:"<<code<<endl;
      cout<<res_data<<endl;
      curl_easy_cleanup(curl);
  }
    curl_global_cleanup();

  }catch(exception &ex){
    cout<<"curl exception:"<<ex.what()<<endl;
  }
}

Java 样例

import java.io.BufferedReader;
import java.io.File;
import java.io.IOException;
import java.io.InputStreamReader;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.mime.MultipartEntity;
import org.apache.http.entity.mime.content.FileBody;
import org.apache.http.entity.mime.content.StringBody;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;

public class httpClientPost {

    public static final String api_id = "ID"; 
    public static final String api_secret = "SECRET"; 
      public static final String type = "BANKCARD"; 
    public static final String filepath = "C:/Users/bankcard.proto";//OCR文件路径
    public static final String POST_URL = "https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result";

    public static void HttpClientPost() throws ClientProtocolException, IOException {
      HttpClient httpclient = new DefaultHttpClient();
      HttpPost post = new HttpPost(POST_URL);
      FileBody fileBody = new FileBody(new File(filepath));
      StringBody id = new StringBody(api_id);
      StringBody secret = new StringBody(api_secret);
      StringBody type = new StringBody(type);
      MultipartEntity entity = new MultipartEntity();
      entity.addPart("file", fileBody);
      entity.addPart("api_id", id);
      entity.addPart("api_secret", secret);
      entity.addPart("type", type);
      post.setEntity(entity);

      HttpResponse response = httpclient.execute(post);
      if (response.getStatusLine().getStatusCode() == 200) {
          HttpEntity entitys = response.getEntity();
          BufferedReader reader = new BufferedReader(
          new InputStreamReader(entitys.getContent()));
        String line = reader.readLine();
        System.out.println(line);
      }else{
        HttpEntity r_entity = response.getEntity();
        String responseString = EntityUtils.toString(r_entity);
        System.out.println("错误码是："+response.getStatusLine().getStatusCode()+"  "+response.getStatusLine().getReasonPhrase());
        System.out.println("出错原因是："+responseString);
        //你需要根据出错的原因判断错误信息，并修改
      }

      httpclient.getConnectionManager().shutdown();
    }


  public static void main(String[] args) throws ClientProtocolException, IOException {
    HttpClientPost();
  }
}

Ruby 样例

require 'net/http/post/multipart'
require 'json'

begin
  uri = URI.parse('https://cloudapi.linkface.cn/ocr/bankcard')
  File.open("bankcard.proto") do |proto|
    req = Net::HTTP::Post::Multipart.new uri.path,
          "file" => UploadIO.new(proto, "application/octet-stream", "bankcard.proto"),
          "api_id" => "ID",
          "api_secret" => "SECRET"
          "type" => "OCR_TYPE"
    res = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
      http.request(req)
    end
    result = JSON.parse(res.body)
    puts result
  end
rescue Exception => e
  puts e.message
end

Python 样例

我们提供的样例支持 Python 2.7 & 3.4–3.7 和 PyPy，其他版本暂不提供，需要您查阅相关资料。

import requests

try:
    host = 'https://cloudapi.linkface.cn'
    url = host + '/ocr/parse_idcard_ocr_result'
    files = {'file': open('/image/file/path', 'rb')}
    data = {'api_id': 'ID','api_secret': 'SECRET'}

    response = requests.post(url, files = files, data = data)
    result = response.json()
    print result
except Exception as e:
    print("type error: " + str(e))

PHP 样例

我们提供的样例是基于 PHP 5.5 与 PHP 5.6 两个版本，其他版本暂不提供，需要您查阅相关资料。

以下样例是基于 PHP 5.5 版本的。

<?php
   $testurl = 'https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result';  
   $filePath = 'C:/Users/bankcard.proto';  //ocr解析结果文件
   $fileContent = '@' . realpath($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET','type' => 'OCR_TYPE'
             'file' => $fileContent);
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $testurl);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);//您可以根据需要，决定是否打开SSL验证
   curl_setopt($ch, CURLOPT_POST,1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
   $output = curl_exec($ch);
   var_dump($output);
   curl_close($ch);
?>

以下样例是基于 PHP 5.6 版本的。

<?php
   $testurl = 'https://cloudapi.linkface.cn/ocr/parse_idcard_ocr_result';  
   $filePath = 'C:/Users/bankcard.proto';  //ocr解析结果文件
   $fileContent = new \CURLFile($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET','type' => 'OCR_TYPE'
             'file' => $fileContent);
   $ch = curl_init();
   curl_setopt($ch, CURLOPT_URL, $testurl);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);//您可以根据需要，决定是否打开SSL验证
   curl_setopt($ch, CURLOPT_POST,1);
   curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
   $output = curl_exec($ch);
   var_dump($output);
   curl_close($ch);
?>

/ocr/parse_idcard_ocr_result

1.接口描述

请求方式

请求 URL

2.请求参数

3.返回参数

4.错误码

5.输入示例

cURL 样例

HTTPie 样例

C++ 样例

Java 样例

Ruby 样例

Python 样例

PHP 样例