/ocr/parse_idcard_ocr_result

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, 不返回原图
return_type boolean 是否返回身份证type,true:返回 false:不返回 ;默认为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
idcard_type string (若return_type设为true则有此返回字段)身份证来源类型:normal 正常拍摄,photocopy 复印件, ps PS, reversion 屏幕翻拍, other 其他, unknown 未知(识别失败)

info数组中字段的结构为:

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

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

字段 类型 说明
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"
  "idcard_type": "normal" //如果return_type设置为true,此处会返回idcard的type
}

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
  • 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);
?>

results matching ""

    No results matching ""