/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 , 不返回原图 |
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);
?>