Classic/VPC環境で利用できます。
特化モデルエンジンを使用して運転免許証の入力情報(key-value)を認識し、抽出します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
| メソッド | URI |
|---|---|
| POST | /id-card |
リクエストヘッダ
CLOVA OCR APIで共通して使用されるヘッダの詳細は、CLOVA OCRのリクエストヘッダをご参照ください。
リクエストボディ
リクエストボディの説明は次の通りです。
Content-Type: application/jsonの場合
リクエストヘッダのContent-Typeがapplication/jsonの場合のリクエストボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
version |
String | - | バージョン情報
|
requestId |
String | Required | 任意の API呼び出しの UUID |
timestamp |
Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
images |
Array | Required | imagesの詳細情報 |
Content-Type: multipart/form-dataの場合
リクエストヘッダのContent-Typeがmultipart/form-dataの場合のリクエストボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
message |
Object | Required | リクエストデータ情報 |
message.version |
String | Required | バージョン情報
|
message.requestId |
String | Required | 任意の API呼び出しの UUID |
message.timestamp |
Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
message.images |
Array | Required | imagesの詳細情報 |
file |
File | Required | OCR認識画像ファイル |
images
imagesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
format |
String | Required | 画像の形式
|
name |
String | Required | 任意の画像名
|
data |
String | Required | Base64でエンコードされた画像データ
|
リクエスト例
リクエストのサンプルコードは次の通りです。
Content-Type: application/jsonの場合
リクエストヘッダのContent-Typeがapplication/jsonの場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
"version": "V2",
"requestId": "string",
"timestamp": 0,
"images": [
{
"format": "png",
"name": "driverlicense_test",
"data":"{Base64でエンコードされた画像データ}"
}
]
}'
Content-Type: multipart/form-dataの場合
リクエストヘッダのContent-Typeがmultipart/form-dataの場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 0, \"images\": [{\"format\": \"png\", \"name\": \"driverlicense_test\"}]}"' \
--form 'file=@"{file}"'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
version |
String | - | バージョン情報
|
requestId |
String | - | API呼び出し UUID |
timestamp |
Integer | - | APIの呼び出し時刻(Timestamp) |
images |
Array | - | imagesの詳細情報 |
images
imagesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
uid |
String | - | 運転免許証画像の UID
|
name |
String | - | 運転免許証の画像名
|
inferResult |
String | - | 運転免許証の画像認識結果
|
message |
String | - | 結果メッセージ |
validationResult |
Object | - | 有効性検査の結果情報 |
validationResult.result |
String | - | 有効性検査の結果コード
|
validationResult.message |
String | - | 有効性検査結果の詳細メッセージ
|
convertedImageInfo |
Object | - | 変換後の画像情報
|
convertedImageInfo.width |
Integer | - | 変換後画像の横長 |
convertedImageInfo.height |
Integer | - | 変換後画像の縦長 |
convertedImageInfo.pageIndex |
Integer | - | 変換後画像ページインデックス |
idCard |
Object | - | 身分証明書の詳細情報 |
idCard.meta |
Object | - | メタ情報 |
idCard.meta.estimatedLanguage |
String | - | OCR推定言語
|
idCard.result |
Object | - | 身分証明書の OCR認識結果 |
result
resultの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
isConfident |
Boolean | - | 各タイプの詳細情報を保有するかどうか
|
dl |
Object | - | 運転免許証情報 |
dl.type |
Array | - | 免許タイプの詳細情報 |
dl.num |
Array | - | 免許番号の詳細情報 |
dl.name |
Array | - | 氏名の詳細情報 |
dl.personalNum |
Array | - | 住民登録番号の詳細情報 |
dl.address |
Array | - | 住所の詳細情報 |
dl.renewStartDate |
Array | - | 更新期間開始日の詳細情報 |
dl.renewEndDate |
Array | - | 更新期間終了日の詳細情報 |
dl.condition |
Array | - | 免許条件の詳細情報 |
dl.code |
Array | - | 免許コードの詳細情報 |
dl.organDonation |
Array | - | 臓器および組織ドナー登録の詳細情報 |
dl.issueDate |
Array | - | 発行日の詳細情報 |
dl.authority |
Array | - | 発行機関の詳細情報 |
rois |
Array | - | オブジェクト枠線の位置情報 |
idType |
String | - | 身分証明書タイプ
|
type
dl.typeの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果のタイプテキスト |
keyText |
String | - | 認識結果のタイプテキストのキー |
confidenceScore |
Float | - | 認識結果のタイプテキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
num
dl.numの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の番号テキスト |
formatted |
Object | - | 認識結果の番号テキスト情報 |
formatted.value |
String | - | 認識結果の番号テキストの値 |
keyText |
String | - | 認識結果の番号テキストのキー |
confidenceScore |
Float | - | 認識結果の番号テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
name
dl.nameの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の名前テキスト |
formatted |
Object | - | 認識結果の名前テキスト情報 |
formatted.value |
String | - | 認識結果の名前テキストの値 |
keyText |
String | - | 認識結果の名前テキストのキー |
confidenceScore |
Float | - | 認識結果の名前テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
personalNum
dl.personalNumの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の住民登録番号テキスト |
formatted |
Object | - | 認識結果の住民登録番号テキスト情報 |
formatted.value |
String | - | 認識結果の住民登録番号テキスト情報 |
keyText |
String | - | 認識結果の住民登録番号テキストのキー |
confidenceScore |
Float | - | 認識結果の住民登録番号テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
address
dl.addressの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の住所テキスト |
formatted |
Object | - | 認識結果の住所テキスト情報 |
formatted.value |
String | - | 認識結果の住所テキストの値 |
keyText |
String | - | 認識結果の住所テキストのキー |
confidenceScore |
Float | - | 認識結果の住所テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
日付オブジェクト情報
日付オブジェクトの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の日付テキスト |
formatted |
Object | - | 認識結果の日付テキスト情報 |
formatted.year |
String | - | 認識結果の日付の年度(yyyy) |
formatted.month |
String | - | 認識結果の日付の月(MM) |
formatted.day |
String | - | 認識結果の日付の日(dd) |
keyText |
String | - | 認識結果の発行テキストのキー |
confidenceScore |
Float | - | 認識結果の日付テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
condition
dl.conditionの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の条件テキスト |
keyText |
String | - | 認識結果の条件テキストのキー |
confidenceScore |
Float | - | 認識結果の条件テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
code
dl.codeの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果のコードテキスト |
formatted |
Object | - | 認識結果のコードテキスト情報 |
formatted.value |
String | - | 認識結果のコードテキストの値 |
keyText |
String | - | 認識結果のコードテキストのキー |
confidenceScore |
Float | - | 認識結果のコードテキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
organDonation
dl.organDonationの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の臓器・組織提供テキスト |
keyText |
String | - | 認識結果の臓器・組織提供テキストのキー |
confidenceScore |
Float | - | 認識結果の臓器・組織提供テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
authority
dl.authorityの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
text |
String | - | 認識結果の発行機関テキスト |
formatted |
Object | - | 認識結果の発行機関テキスト情報 |
formatted.value |
String | - | 認識結果の発行機関テキストの値 |
keyText |
String | - | 認識結果の発行機関テキストのキー |
confidenceScore |
Float | - | 認識結果の発行機関テキストの信頼度
|
boundingPolys |
Array | - | boundingPolyの詳細情報 |
maskingPolys |
Array | - | maskingPolyの詳細情報 |
rois
roisの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
| フィールド | タイプ | 必須の有無 | 説明 |
| --- | --- | --- | --- |
x |
Float | - | オブジェクト枠線の位置 X軸の座標 |
y |
Float | - | オブジェクト枠線の位置 Y軸の座標 |
boundingPolys
boundingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
maskingPolys
maskingPolysの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
vertices |
Array | - | verticesの詳細情報 |
boundingPolyVertices
boundingPolyVerticesの説明は次の通りです。
| フィールド | タイプ | 必須の有無 | 説明 |
|---|---|---|---|
x |
Float | - | X軸の座標 |
y |
Float | - | Y軸の座標 |
レスポンスステータスコード
CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。
レスポンス例
レスポンスのサンプルコードは次の通りです。
成功
呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725409664957,
"images": [
{
"uid": "{uid}",
"name": "driverlicense_test",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
},
"idCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"isConfident": true,
"dl": {
"type": [
{
"text": "1種大型 1種普通 1種小型 特殊(大型牽引、小型牽引、救難)2種普通 2種小型二輪",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 6.875,
"y": 20.625
},
{
"x": 77.5,
"y": 20.625
},
{
"x": 77.5,
"y": 42.5
},
{
"x": 6.875,
"y": 42.5
}
]
}
]
}
],
"num": [
{
"text": "**-**-******-**",
"formatted": {
"value": "**-**-******-**"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 270.66333,
"y": 81.96319
},
{
"x": 615.7258,
"y": 83.148964
},
{
"x": 615.59015,
"y": 122.63947
},
{
"x": 270.52765,
"y": 121.4537
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 404.75287,
"y": 78.474884
},
{
"x": 619.68854,
"y": 79.213486
},
{
"x": 619.5257,
"y": 126.60209
},
{
"x": 404.59003,
"y": 125.86349
}
]
}
]
}
],
"name": [
{
"text": "ホン**",
"formatted": {
"value": "ホン**"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 268.125,
"y": 130.0
},
{
"x": 358.75,
"y": 130.0
},
{
"x": 358.75,
"y": 164.375
},
{
"x": 268.125,
"y": 164.375
}
]
}
],
"maskingPolys": []
}
],
"personalNum": [
{
"text": "******-*******",
"formatted": {
"value": "******-*******"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 264.71436,
"y": 161.93407
},
{
"x": 496.74896,
"y": 159.34149
},
{
"x": 497.16132,
"y": 196.25029
},
{
"x": 265.1267,
"y": 198.84286
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 376.99954,
"y": 156.98816
},
{
"x": 500.39862,
"y": 155.60939
},
{
"x": 500.89346,
"y": 199.89995
},
{
"x": 377.49442,
"y": 201.27872
}
]
}
]
}
],
"address": [
{
"text": "ソウル市***",
"formatted": {
"value": "ソウル市***"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 263.125,
"y": 232.5
},
{
"x": 301.25,
"y": 232.5
},
{
"x": 301.25,
"y": 258.75
},
{
"x": 263.125,
"y": 258.75
}
]
}
],
"maskingPolys": []
}
],
"renewStartDate": [
{
"text": "2029.01.01",
"formatted": {
"year": "2029",
"month": "01",
"day": "01"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 402.39316,
"y": 300.80316
},
{
"x": 531.2038,
"y": 300.008
},
{
"x": 531.3579,
"y": 324.9801
},
{
"x": 402.54727,
"y": 325.7752
}
]
}
],
"maskingPolys": []
}
],
"renewEndDate": [
{
"text": "2029 12.31",
"formatted": {
"year": "2029",
"month": "12",
"day": "31"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 425.987,
"y": 332.6018
},
{
"x": 481.51587,
"y": 329.9576
},
{
"x": 482.8507,
"y": 357.98932
},
{
"x": 427.32184,
"y": 360.6335
}
]
}
],
"maskingPolys": []
}
],
"condition": [
{
"text": "件8",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 341.875,
"y": 361.25
},
{
"x": 367.5,
"y": 361.25
},
{
"x": 367.5,
"y": 388.75
},
{
"x": 341.875,
"y": 388.75
}
]
}
],
"maskingPolys": []
}
],
"code": [
{
"text": "H1***",
"formatted": {
"value": "H1***"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 582.5,
"y": 351.87497
},
{
"x": 690.625,
"y": 351.87497
},
{
"x": 690.625,
"y": 379.99997
},
{
"x": 582.5,
"y": 379.99997
}
]
}
],
"maskingPolys": []
}
],
"organDonation": [
{
"text": "臓器および組織ドナー登録",
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 59.375,
"y": 454.375
},
{
"x": 105.625,
"y": 454.375
},
{
"x": 105.625,
"y": 479.375
},
{
"x": 59.375,
"y": 479.375
}
]
}
]
}
],
"issueDate": [
{
"text": "2019.09.10",
"formatted": {
"year": "2019",
"month": "09",
"day": "10"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 249.375,
"y": 443.75
},
{
"x": 368.125,
"y": 443.75
},
{
"x": 368.125,
"y": 475.0
},
{
"x": 249.375,
"y": 475.0
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 246.28294,
"y": 440.82266
},
{
"x": 411.842,
"y": 440.82266
},
{
"x": 411.842,
"y": 477.9273
},
{
"x": 246.28294,
"y": 477.9273
}
]
}
]
}
],
"authority": [
{
"text": "ソウル地方警察庁",
"formatted": {
"value": "ソウル地方警察庁長"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 402.79678,
"y": 436.09882
},
{
"x": 651.7483,
"y": 433.49652
},
{
"x": 652.1772,
"y": 474.53296
},
{
"x": 403.2257,
"y": 477.13528
}
]
}
],
"maskingPolys": []
}
]
},
"rois": [
{
"vertices": [
{
"x": -4.7505364,
"y": -5.066147
},
{
"x": 712.13684,
"y": -2.8448386
},
{
"x": 714.93665,
"y": 480.58566
},
{
"x": -2.094209,
"y": 492.42014
}
]
}
],
"idtype": "Driver's License"
}
}
}
]
}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235840459,
"images": [
{
"uid": "{uid}",
"name": "idcard_sample",
"inferResult": "ERROR",
"message": "Read page:0 error.",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}