/ocr/idcard

1.接口描述

该 API 用于识别静态身份证图像上的文字信息。

算法主要针对第二代居民身份证,其他类型身份证检测结果准确率较低,仅供参考。

  • 图片要求

    1. 格式为 JPG(JPEG),BMP,PNG,GIF,TIFF
    2. 宽和高大于 8px,小于等于4000px
    3. 小于等于 5 MB
  • 支持自动识别人脸方向

    1. 上传的图片中包含有 exif 方向信息,先按此信息旋转、翻转后再做识别人脸方向并调整,并在返回结果中给出 exif_orientation 字段(如果没有则不输出)
    2. 如果照片方向混乱且 exif 方向信息不存在或不正确,自动识别人脸方向并调整

请求方式

POST

请求 URL

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

2.请求参数

字段 类型 必需 描述
api_id string API 账户
api_secret string API 密钥
file file 见下方注释 需上传的图片文件。上传本地图片进行检测时选取此参数
url string 见下方注释 图片网络地址。采用抓取网络图片方式时需选取此参数
image_id string 见下方注释 图片的id。在云端上传过图片可采用
auto_rotate boolean 开启图片自动旋转功能。开通:true,不开通:false。默认开通
side string 身份证朝向。身份证正面(有照片的一面): front ,身份证反面:back ,系统自动识别auto 。默认值为 auto
return_type boolean 是否返回身份证type,true:返回 false:不返回 ;默认为false

请求参数 file,urlimage_id 三选一。

url 中含有不少特殊字符,若将 URL 放入 Query String 中则需要对这些字符进行转义,所有中文和特殊字符必需以UTF-8编码转义。 目前支持 http/https 等协议的网络地址。下载限时 5s,超时后仍未下载完成则属于失败。 参数 file 需把图片文件的内容以 multipart/form-data 的形式放到 POST 消息体中。

3.返回参数

字段 类型 说明
request_id string 本次请求的id
status string 状态,正常为 OK ,其他值表示失败,详见错误码
image_id string 图片上传云端后的id 。使用file、url方式提交图片会返回此参数
exif_orientation integer exif 信息。若图片含有exif信息返回此参数,返回值范围为 1~8 。返回值的具体含义请参考 http://jpegclub.org/exif_orientation.html
side string 身份证方向信息。front 代表身份证正面,back 代表身份证反面
rotate string 旋转角度。开启自动旋转功,返回旋转的角度值,可能的值为 cw90,cw180,cw270,表明顺时针旋转的角度。如果没有发生旋转,则不返回此字段
info object 身份证文字信息,详见info数组中字段的结构
validity object 各项信息有效性,详见validity数组中字段的结构
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 地址
number string 身份证号
authority string 签发机关
timelimit string 身份证有效期

validity数组中字段的结构:

字段 类型 说明
name boolean 如果小于两个字符,或者包含数字,为 false,反之为 true
sex boolean 当检测出的性别与身份证号所表示的性别匹配,则为 true,反之为 false
birthday boolean 当检测出的出生日期与身份证号中的生日字段匹配,则值为 true,反之为 false
address boolean 身份证号码前6位为地区码,当其在预设的码表内,则值为 true,否则为 false
number boolean 当身份证号码符合校验规则,则值为 true,反之,为 false
authority boolean 检测出签发机构后两字是“分局”或“安局”,则为 true,否则为 false
timelimit boolean 身份证有效期长度为 17 位,第八位为 -,年份大于等于 2000 年且小于等于 2050 年时,该值为 true,否则为 false

infovalidity 结构中 authoritytimelimit 字段为身份证反面内容, 其余为身份证正面内容。

当上传的图片是非身份证图片时,系统不会报错,但这种情况下 validity 中所有字段都会为 false,请参考 validity 字段进行判断。

  • 身份证正面
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "exif_orientation": 1,
  "side": "front",
  "rotate": "cw270",
  "image_id":"xxxxx",
  "info": {
    "name": "小红",
    "sex": "女",
    "nation": "汉",
    "year": "1990",
    "month": "2",
    "day": "14",
    "address": "北京市海淀区xx路xx号",
    "number": "360722199002148230"
  },
  "validity": {
    "name": true,
    "sex": true,
    "birthday": true,
    "address": true,
    "number": true
  },
  "type": "normal" //若return_type设置为`true`,则返回此字段
}
  • 身份证反面
{
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
  "status": "OK",
  "side": "back",
  "image_id":"xxxxx",
  "info": {
    "authority": "宜昌市公安局西陵分局",
    "timelimit": "20060529-20260529"
  },
  "validity": {
    "authority": true,
    "timelimit": true
  },
  "type": "normal" //若return_type设置为`true`,则返回此字段
}

4.错误码

以下请求参数列表仅列出了接口请求参数,其它参数见公共请求参数页面。

状态码 status 字段 说明
400 ENCODING_ERROR 参数非UTF-8编码
400 DOWNLOAD_TIMEOUT 网络地址图片获取超时
400 IMAGE_ID_NOT_EXIST 图片不存在
400 CORRUPT_IMAGE 文件不是图片文件或已经损坏
400 DOWNLOAD_ERROR 网络地址图片获取失败
400 DOWNLOAD_TIMEOUT 图片下载超时
400 IMAGE_FILE_SIZE_TOO_BIG 图片体积过大
400 INVALID_IMAGE_FORMAT_OR_SIZE 图片大小或格式不符合要求
400 INVALID_ARGUMENT 请求参数错误,具体原因见 reason 字段内容
401 UNAUTHORIZED 账号或密钥错误
401 KEY_EXPIRED 账号过期,具体情况见 reason 字段内容
403 RATE_LIMIT_EXCEEDED 调用频率超出限额
403 NO_PERMISSION 无调用权限
403 OUT_OF_QUOTA 调用次数超出限额
404 NOT_FOUND 请求路径错误
500 INTERNAL_ERROR 服务器内部错误
{
  "status": "INVALID_ARGUMENT",
  "reason": "must specify 'image_id', 'file' or 'url' argument",
  "request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}

5.输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/ocr/idcard?api_id=ID&api_secret=SECRET" \
  -F file=@/PATH/TO/IMAGE
  • HTTPie 样例
http -f POST "https://cloudapi.linkface.cn/ocr/idcard?api_id=ID&api_secret=SECRET" \
  file@/PATH/TO/IMAGE
  • 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,"file",
                  CURLFORM_FILE, argc[1], CURLFORM_END);

      curl_easy_setopt(curl, CURLOPT_URL, "https://cloudapi.linkface.cn/ocr/idcard");
      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 filepath = "C:/Users/card.jpg";//图片路径
      public static final String POST_URL = "https://cloudapi.linkface.cn/ocr/idcard";

      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);
            MultipartEntity entity = new MultipartEntity();
            entity.addPart("file", fileBody);
            entity.addPart("api_id", id);
            entity.addPart("api_secret", secret);
            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/idcard')
  File.open("px.jpg") do |jpg|
    req = Net::HTTP::Post::Multipart.new uri.path,
          "file" => UploadIO.new(jpg, "image/jpeg", "idcard.jpg"),
          "api_id" => "ID",
          "api_secret" => "SECRET"
    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/idcard';  
   $filePath = 'C:/Users/idcard.jpg';  //图片路径
   $fileContent = '@' . realpath($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET',
             '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/idcard';  
   $filePath = 'C:/Users/idcard.jpg';  //图片路径
   $fileContent = new \CURLFile($filePath);
   $post_data = array ('api_id' => 'ID','api_secret' => 'SECRET',
             '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 ""