version
| 문서 버전 | 변경일자 | 변경사항 |
|---|---|---|
| v1.0.0 | 2021-07-07 | 최초 작성 |
| v1.0.1 | 2024-09-26 | 콘텐츠 항목 정리 및 문구 개선 |
개요
본 문서에서는 Document OCR의 공통요청 및 응답 바디에 대해 설명하고 API 구현 예제를 제공합니다.
공통 요청
참고
- Document OCR은 Post URL과 헤더를 기준으로 상품을 구분하며 요청 바디는 모두 동일합니다.
- Post URL과 헤더, 에러코드에 대한 정보는 CLOVA OCR 개요 문서를 참조해 주십시오.
요청 예시
{
"version": "V2",
"requestId": "string",
"timestamp": 0,
"images": [
{
"format": "jpg",
"name": "document ocr test",
"data": "/9j/4AAQ*****************"
}
]
}
요청 바디
Content-Type : application/json
- CURL example:
curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--data-raw '{"images":[{"format":"jpg","name":"demo","data":"your image base64 bytes"}],"requestId":"guide-json-demo","version":"V2","timestamp":1584062336793}'
- JSON 요청 바디 필드
| 필드명 | 필수 여부 | 타입 | 설명 | 제약 사항 |
|---|---|---|---|---|
| version | Y | string | V2로 고정 |
|
| requestId | Y | string | 임의의 UUID 값 입력 | |
| timestamp | Y | integer | 임의의 timestamp 값을 숫자로 입력 | |
| images | Y | string | JSON array로 작성하며, 호출당 1개의 이미지 array만 작성 가능 | |
| images.format | Y | string | jpg, jpeg, png, pdf, tiff 중 택일하여 이미지 포맷을 입력 |
pdf, tiff는 단일 페이지 형식원지원 |
| image.data | Y | string | BASE64로 인코딩된 이미지 바이트를 입력 | 특화 문서의 경우 보안을 위해 인코딩된 이미지 바이트만 지원 |
| image.name | Y | string | 임의의 이미지명 입력 | 이미지를 식별하는 데 사용되며 응답 결과 검증에 사용 |
Content-Type : multipart/form-data
- CURL example:
curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--form 'message={"images":[{"format":"png","name":"demo"}],"requestId":"guide-demo","version":"V2","timestamp":1584062336793}' \
--form 'file=@image.png'
- Form Data 요청 바디 필드
| 필드명 | 필수 여부 | 타입 | 설명 | 제약 사항 |
|---|---|---|---|---|
| version | Y | string | V2로 고정 |
|
| requestId | Y | string | 임의의 UUID 값 입력 | |
| timestamp | Y | integer | 임의의 timestamp 값을 숫자로 입력 | |
| images | Y | string | JSON array로 작성하며, 호출당 1개의 이미지 array만 작성 가능 | |
| images.format | Y | string | jpg, jpeg, png, pdf, tiff 중 택일하여 이미지 포맷을 입력 |
pdf, tiff는 단일 페이지 형식을 지원합니다. |
| image.name | Y | string | 임의의 이미지명 입력 | 이미지를 식별하는 데 사용되며 응답 결과 검증에 사 |
응답 바디
신용카드 예시
{
"version": "V2",
"requestId": "string",
"timestamp": 1613984515468,
"images": [
{
"creditCard": {
"result": {
"number": {
"text": "5307123456789012",
"confidence": 0.96435016,
"boundingPoly": {
"vertices": [
{
"x": 64.0,
"y": 218.0
},
{
"x": 582.0,
"y": 222.0
},
{
"x": 582.0,
"y": 265.0
},
{
"x": 64.0,
"y": 261.0
}
]
},
"subBoundingPolys": [
{
"vertices": [
{
"x": 65.0,
"y": 222.0
},
{
"x": 175.0,
"y": 225.0
},
{
"x": 174.0,
"y": 260.0
},
{
"x": 64.0,
"y": 257.0
}
]
},
{
"vertices": [
{
"x": 202.0,
"y": 225.0
},
{
"x": 312.0,
"y": 225.0
},
{
"x": 312.0,
"y": 262.0
},
{
"x": 202.0,
"y": 262.0
}
]
},
{
"vertices": [
{
"x": 340.0,
"y": 225.0
},
{
"x": 445.0,
"y": 225.0
},
{
"x": 445.0,
"y": 260.0
},
{
"x": 340.0,
"y": 260.0
}
]
},
{
"vertices": [
{
"x": 470.0,
"y": 222.0
},
{
"x": 582.0,
"y": 222.0
},
{
"x": 582.0,
"y": 260.0
},
{
"x": 470.0,
"y": 260.0
}
]
}
]
}
}
},
"uid": "5f824ebe5b9744bb81bd3e1ef7f42e4e",
"name": "testV2Demo",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}
신용카드 응답 바디
신용카드 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 공통 객체 정보를 참조해 주십시오.
1. 응답 바디 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| uid | string | API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용 |
| name | string | 요청 바디의 images.name에 입력한 이미지명 |
| inferResult | string | 이미지 인식 결과SUCCESS: 이미지 인식 성공FAILURE: 이미지 인식 실패ERROR: 이미지 인식 처리예외 |
| message | string | 이미지 인식 성공 시 SUCCESS 표시이미지 인식 실패 시 오류 메시지 표시 |
| creditCard | json object | creditCard 객체 참조 |
| validationResult | json object | 유효성 검사 결과 |
| validationResult.result | string | 유효성 검사 결과 코드NO_REQUESTED: 검증 작업을 요청하지 않음UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락ERROR: 검증 실행에 오류 발생 VALID: 검증 결과가 유효함 INVALID: 검증 결과가 유효하지 않음 ※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨 |
| validationResult.message | string | Validation 세부 메시지로 항상 응답되는 값은 아님 |
| convertedImageInfo | json object | 이미지 포맷이 pdf 또는 tiff인 경우 응답좌표값은 이미지로 변환된 호출 파일을 기준으로 함 |
| convertedImageInfo.width | integer | 변환 이미지 가로 길이 |
| convertedImageInfo.height | integer | 변환 이미지 세로 길이 |
| convertedImageInfo.pageIndex | integer | pdf 또는 tiff의 페이지 인덱스 |
2. creditCard 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| meta | json object | 메타 정보 |
| meta.estimatedLanguage | string | OCR에서 추정한 언어 ( en: 영어, ja: 일본어, ko: 한국어) |
| result | json object | 인식 결과 객체 |
| result.number | Field object | field 객체 참조 |
| result.validThru | Field object | field 객체 참조 |
| result.name | Field object | 카드 소유자 이름 field 객체 참조 |
신분증 예시
주민등록증 응답 예시
{
"version": "V2",
"requestId": "string",
"timestamp": 1613984543939,
"images": [
{
"idCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"isConfident": true,
"ic": {
"name": [
{
"text": "소닉",
"formatted": {
"value": "소닉"
},
"boundingPolys": [
{
"vertices": [
{
"x": 93.0,
"y": 135.0
},
{
"x": 257.0,
"y": 135.0
},
{
"x": 257.0,
"y": 161.0
},
{
"x": 93.0,
"y": 161.0
}
]
}
]
}
],
"personalNum": [
{
"text": "910623-1062372",
"formatted": {
"value": "910623-1062372"
},
"boundingPolys": [
{
"vertices": [
{
"x": 83.0,
"y": 166.0
},
{
"x": 260.0,
"y": 166.0
},
{
"x": 260.0,
"y": 186.0
},
{
"x": 83.0,
"y": 186.0
}
]
}
]
}
],
"address": [
{
"text": "서울특별시 종로구 종로1가 24 르메이에르 종로타운",
"formatted": {
"value": "서울특별시 종로구 종로1가 24 르메이에르 종로타운"
},
"boundingPolys": [
{
"vertices": [
{
"x": 43.0,
"y": 232.0
},
{
"x": 148.0,
"y": 232.0
},
{
"x": 148.0,
"y": 255.0
},
{
"x": 43.0,
"y": 255.0
}
]
},
{
"vertices": [
{
"x": 47.0,
"y": 212.0
},
{
"x": 150.0,
"y": 212.0
},
{
"x": 150.0,
"y": 234.0
},
{
"x": 47.0,
"y": 234.0
}
]
},
{
"vertices": [
{
"x": 154.0,
"y": 232.0
},
{
"x": 240.0,
"y": 232.0
},
{
"x": 240.0,
"y": 255.0
},
{
"x": 154.0,
"y": 255.0
}
]
},
{
"vertices": [
{
"x": 156.0,
"y": 212.0
},
{
"x": 219.0,
"y": 212.0
},
{
"x": 219.0,
"y": 234.0
},
{
"x": 156.0,
"y": 234.0
}
]
},
{
"vertices": [
{
"x": 224.0,
"y": 212.0
},
{
"x": 302.0,
"y": 212.0
},
{
"x": 302.0,
"y": 235.0
},
{
"x": 224.0,
"y": 235.0
}
]
},
{
"vertices": [
{
"x": 305.0,
"y": 213.0
},
{
"x": 333.0,
"y": 213.0
},
{
"x": 333.0,
"y": 234.0
},
{
"x": 305.0,
"y": 234.0
}
]
}
]
}
],
"issueDate": [
{
"text": "2011.3. 6.",
"formatted": {
"year": "2011",
"month": "03",
"day": "06"
},
"boundingPolys": [
{
"vertices": [
{
"x": 261.0,
"y": 314.0
},
{
"x": 351.0,
"y": 314.0
},
{
"x": 351.0,
"y": 336.0
},
{
"x": 261.0,
"y": 336.0
}
]
},
{
"vertices": [
{
"x": 354.0,
"y": 314.0
},
{
"x": 376.0,
"y": 314.0
},
{
"x": 376.0,
"y": 334.0
},
{
"x": 354.0,
"y": 334.0
}
]
}
]
}
],
"authority": [
{
"text": "소닉대통령추진회 소덕회장",
"formatted": {
"value": "소닉대통령추진회 소덕회장"
},
"boundingPolys": [
{
"vertices": [
{
"x": 172.0,
"y": 338.0
},
{
"x": 346.0,
"y": 338.0
},
{
"x": 346.0,
"y": 366.0
},
{
"x": 172.0,
"y": 366.0
}
]
},
{
"vertices": [
{
"x": 347.0,
"y": 338.0
},
{
"x": 435.0,
"y": 336.0
},
{
"x": 435.0,
"y": 363.0
},
{
"x": 348.0,
"y": 365.0
}
]
}
]
}
]
},
"idtype": "ID Card"
}
},
"uid": "0012374f247f4e70966d35eaa3c41d2a",
"name": "testV2Demo",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}
신분증 응답 바디
신분증 OCR의 응답 바디를 설명합니다.
신분증은 주민등록증(구형/신형), 운전면허증(구형/신형), 외국인등록증, 여권 인식을 지원합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.
1. 응답 바디 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| uid | string | API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용 |
| name | string | 요청 바디의 images.name에 입력한 이미지명 |
| inferResult | string | 이미지 인식 결과SUCCESS: 이미지 인식 성공FAILURE: 이미지 인식 실패ERROR: 이미지 인식 처리예외 |
| message | string | 이미지 인식 성공 시 SUCCESS 표시이미지 인식 실패 시 오류 메시지 표시 |
| idCard | json object | idCard 객체 참조 |
| validationResult | json object | 유효성 검사 결과 |
| validationResult.result | string | 유효성 검사 결과 코드 NO_REQUESTED: 검증 작업을 요청하지 않음UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락ERROR: 검증 실행에 오류 발생 VALID: 검증 결과가 유효함 INVALID: 검증 결과가 유효하지 않음 ※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨 |
| validationResult.message | string | Validation 세부 메시지로 항상 응답되는 값은 아님 |
| convertedImageInfo | json object | 이미지 포맷이 pdf 또는 tiff인 경우 응답좌표값은 이미지로 변환된 호출 파일을 기준으로 함 |
| convertedImageInfo.width | integer | 변환 이미지 가로 길이 |
| convertedImageInfo.height | integer | 변환 이미지 세로 길이 |
| convertedImageInfo.pageIndex | integer | pdf 또는 tiff의 페이지 인덱스 |
2. idCard 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| meta | json object | 메타 정보 |
| meta.estimatedLanguage | string | OCR에서 추정한 언어 ( en: 영어, ja: 일본어, ko: 한국어) |
| result | json object | 인식 결과 객체 |
| result.isConfident | boolean | 신뢰성 자격 요건을 반영하는 지표 각 ID 유형에 필요한 세부 정보가 있으면 true로 출력되고, 그렇지 않으면 false로 출력됨 |
| result.IDType | string | 신분증 유형 반환 값은 "신분증", "운전면허증", "여권", "알 수 없음" 중 하나임 |
| result.rois | BoundingPoly[] | 객체 테두리 위치 정보 |
| result.ic | json object | 주민등록증 정보 |
| result.ic.name | StringObject[] | 이름(한국어) |
| result.ic.personalNum | StringObject[] | 주민등록번호 |
| result.ic.address | StringObject[] | 주소 |
| result.ic.issueDate | DateObject[] | 발급 일자 |
| result.ic.authority | StringObject[] | 발급 기관 |
| result.dl | json object | 운전면허증 정보 |
| result.dl.type | BaseObject[] | 면허 유형 |
| result.dl.num | StringObject[] | 면허 번호 |
| result.dl.name | StringObject[] | 이름(한국어) |
| result.dl.personalNum | StringObject[] | 주민등록번호 |
| result.dl.address | StringObject[] | 주소 |
| result.dl.renewStartDate | DateObject[] | 갱신기간 시작일 |
| result.dl.renewEndDate | DateObject[] | 갱신기간 종료일 |
| result.dl.condition | StringObject[] | 면허 조건 |
| result.dl.code | StringObject[] | 면허 코드 |
| result.dl.organDonation | BaseObject[] | 장기 및 조직 기증 등록 |
| result.dl.issueDate | DateObject[] | 발급 일자 |
| result.dl.authority | StringObject[] | 발급 기관 |
| result.pp | json object | 여권 정보 |
| result.pp.type | StringObject[] | 여권 유형 |
| result.pp.issueCountry | BaseObject[] | 발급 국가 |
| result.pp.num | StringObject[] | 여권 번호 |
| result.pp.surName | StringObject[] | 성 |
| result.pp.givenName | StringObject[] | 이름 |
| result.pp.nationality | StringObject[] | 국적 |
| result.pp.birthDate | DateObject[] | 생년월일 |
| result.pp.personalNum | StringObject[] | 주민등록번호 |
| result.pp.sex | StringObject[] | 성별 |
| result.pp.issueDate | DateObject[] | 발급 일자 |
| result.pp.expireDate | DateObject[] | 만료 일자 |
| result.pp.authority | BaseObject[] | 발행 기관 |
| result.pp.fullNameKor | StringObject[] | 이름(한국어) |
| result.pp.MRZ1 | StringObject[] | 기계판독영역(Machine Readable Zone, MRZ) 1 |
| result.pp.MRZ2 | StringObject[] | 기계판독영역(Machine Readable Zone, MRZ) 2 |
| result.ac | json object | 외국인 등록증 정보 |
| result.ac.alienRegNum | StringObject[] | 외국인 등록번호 |
| result.ac.sex | StringObject[] | 성별 |
| result.ac.name | StringObject[] | 이름 |
| result.ac.nationality | StringObject[] | 국적 |
| result.ac.visaType | StringObject[] | 비자 유형 |
| result.ac.issueDate | DateObject[] | 발급 일자 |
| result.ac.authority | StringObject[] | 발급 기관 |
| result.ac.authorityEng | StringObject[] | 발급 기관(영문) |
| result.ac.alienRegNumEtc | StringObject[] | 외국인 등록번호 등 |
명함 예시
{
"version": "V2",
"requestId": "string",
"timestamp": 1613984872349,
"images": [
{
"nameCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"name": [
{
"text": "홍길동",
"boundingPolys": [
{
"vertices": [
{
"x": 286.0,
"y": 194.0
},
{
"x": 348.0,
"y": 194.0
},
{
"x": 348.0,
"y": 266.0
},
{
"x": 286.0,
"y": 266.0
}
]
}
]
}
],
"nameFurigana": [],
"company": [
{
"text": "우리은행",
"boundingPolys": [
{
"vertices": [
{
"x": 317.0,
"y": 274.0
},
{
"x": 356.0,
"y": 274.0
},
{
"x": 356.0,
"y": 316.0
},
{
"x": 317.0,
"y": 316.0
}
]
}
]
}
],
"department": [],
"address": [
{
"text": "(홍길동)",
"boundingPolys": [
{
"vertices": [
{
"x": 338.0,
"y": 189.0
},
{
"x": 414.0,
"y": 189.0
},
{
"x": 414.0,
"y": 288.0
},
{
"x": 338.0,
"y": 288.0
}
]
}
]
}
],
"position": [
{
"text": "소장",
"boundingPolys": [
{
"vertices": [
{
"x": 286.0,
"y": 194.0
},
{
"x": 348.0,
"y": 194.0
},
{
"x": 348.0,
"y": 266.0
},
{
"x": 286.0,
"y": 266.0
}
]
}
]
}
],
"mobile": [
{
"text": "010-1234-5678",
"boundingPolys": [
{
"vertices": [
{
"x": 297.0,
"y": 183.0
},
{
"x": 396.0,
"y": 183.0
},
{
"x": 396.0,
"y": 305.0
},
{
"x": 297.0,
"y": 305.0
}
]
}
]
}
],
"tel": [
{
"text": "123-4567-8901",
"boundingPolys": [
{
"vertices": [
{
"x": 338.0,
"y": 189.0
},
{
"x": 414.0,
"y": 189.0
},
{
"x": 414.0,
"y": 288.0
},
{
"x": 338.0,
"y": 288.0
}
]
}
]
}
],
"fax": [],
"email": [],
"homepage": []
}
},
"uid": "3277149ad2324de0b412669f7eac474a",
"name": "testV2Demo",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}
명함 응답 바디
명함 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.
1. 응답 바디 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| uid | string | API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용 |
| name | string | 요청 바디의 images.name에 입력한 이미지명 |
| inferResult | string | 이미지 인식 결과SUCCESS: 이미지 인식 성공FAILURE: 이미지 인식 실패ERROR: 이미지 인식 처리예외 |
| message | string | 이미지 인식 성공 시 SUCCESS 표시이미지 인식 실패 시 오류 메시지 표시 |
| nameCard | json object | nameCard 객체 참조 |
| validationResult | json object | 유효성 검사 결과 |
| validationResult.result | string | 유효성 검사 결과 코드 NO_REQUESTED: 검증 작업을 요청하지 않음UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락ERROR: 검증 실행에 오류 발생 VALID: 검증 결과가 유효함 INVALID: 검증 결과가 유효하지 않음 ※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨 |
| validationResult.message | string | Validation 세부 메시지로 항상 응답되는 값은 아님 |
| convertedImageInfo | json object | 이미지 포맷이 pdf 또는 tiff인 경우 응답좌표값은 이미지로 변환된 호출 파일을 기준으로 함 |
| convertedImageInfo.width | integer | 변환 이미지 가로 길이 |
| convertedImageInfo.height | integer | 변환 이미지 세로 길이 |
| convertedImageInfo.pageIndex | integer | pdf 또는 tiff의 페이지 인덱스 |
2. nameCard 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| meta | json object | 메타 정보 |
| meta.estimatedLanguage | string | OCR에서 추정한 언어 (en: 영어, ja: 일본어, ko: 한국어) |
| result | json object | 인식 결과 객체 |
| result.name | StringObject[] | 이름 정보 |
| result.nameFurigana | StringObject[] | 후리가나 이름 정보(언어가 ja일 때만 응답) |
| result.company | StringObject[] | 회사 정보 |
| result.department | StringObject[] | 부서 정보 |
| result.address | StringObject[] | 주소 정보 |
| result.position | StringObject[] | 직급 정보 |
| result.mobile | TelObject[] | 휴대폰 정보 |
| result.tel | TelObject[] | 전화 정보 |
| result.fax | TelObject[] | 팩스 정보 |
| result.email | StringObject[] | 이메일 정보 |
| result.homepage | StringObject[] | 홈페이지 정보 |
공통 객체 정보
Document OCR 각 상품의 응답 바디는 아래의 공통 하위 객체를 응답 전문에 반환합니다.
본 챕터에서는 공통 하위 객체에 대한 세부사항을 설명합니다.
field 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식된 텍스트 |
| confidence | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
| boundingPoly | BoundingPoly object | boundingPoly 객체 참조 |
| subBoundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
boundingPoly 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| vertices | vertices object | vertices 객체 참조 |
vertices 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| x | float | x축 좌표값 |
| y | float | y축 좌표값 |
baseObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식된 텍스트 |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
dateObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식된 텍스트 |
| formatted | json object | 인식된 텍스트에 대한 추가 정보 |
| formatted.year | string | 연. 네 자리 숫자로 연도를 나타냄. 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| formatted.month | string | 월. 두 자리 숫자로 월을 나타냄. 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| formatted.day | string | 일. 두 자리 숫자로 날짜를 나타냄. 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| maskingPolys | BoundingPoly[] | 개인정보 마스킹 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
timeObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식된 텍스트 |
| formatted | json object | 인식된 텍스트에 대한 추가 정보 |
| formatted.hour | string | 시. 두 자리 숫자로 시를 나타냄 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| formatted.minute | string | 분. 두 자리 숫자로 분을 나타냄 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| formatted.second | string | 초. 두 자리 숫자로 초를 나타냄 빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름. |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| maskingPolys | BoundingPoly[] | 개인정보 마스킹 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
TelObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식된 텍스트 |
| formatted | json object | 인식된 텍스트에 대한 추가 정보 |
| formatted.value | string | 전화번호 유형을 나타내는 서식 텍스트 주로 숫자 문자열 형태로 표시되지만 전화 식별자(+)를 포함할 수 있음. 인식 세분화에 실패하면 빈 문자열일 수 있음 |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
FloatObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식 텍스트 |
| formatted | json object | 인식된 텍스트에 대한 추가 정보 |
| formatted.value | string | 실수 유형을 나타내는 서식 있는 텍스트 실수 문자열 유형. 품목의 개수와 가격을 설명하는 데 유용함. 인식 세분화에 실패하면 빈 문자열일 수 있음 |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
StringObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| text | string | 인식 텍스트 |
| formatted | json object | 인식된 텍스트에 대한 추가 정보 |
| formatted.value | string | 정제된 텍스트. 정제 과정은 각 신분증의 분류에 따라 다름. 빈 문자열일 수 있음. |
| boundingPolys | BoundingPoly[] | boundingPoly 객체 참조 |
| maskingPolys | BoundingPoly[] | 개인정보 |
| keyText | string | 인식된 텍스트와 관련된 키 값 |
| confidenceScore | float | 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음 |
PoiObject 객체 필드
| 필드명 | 유형 | 설명 |
|---|---|---|
| gid | string | 고유 ID |
| title | string | 상호명 |
| phone | string | 전화번호 |
| address | string | 주소 |
| roadAddress | string | 도로명주소 |
| biznum | string | 사업자번호 (아직 정식으로 지원되지 않아 null일 수 있으나 추후 추가될 수 있음) |
| confidence | string | 신뢰도 (0~1 사이의 값을 가지며 값이 클수록 정확도가 높음) |
API 예제
다음은 각 언어별 CLOVA OCR Document API 구현 예제입니다
multipart/form-data 요청 예제
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;
import org.json.JSONArray;
import org.json.JSONObject;
public class OCRAPIDemo {
public static void main(String[] args) {
String apiURL = "YOUR_API_URL";
String secretKey = "YOUR_SECRET_KEY";
String imageFile = "YOUR_IMAGE_FILE";
try {
URL url = new URL(apiURL);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setUseCaches(false);
con.setDoInput(true);
con.setDoOutput(true);
con.setReadTimeout(30000);
con.setRequestMethod("POST");
String boundary = "----" + UUID.randomUUID().toString().replaceAll("-", "");
con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
con.setRequestProperty("X-OCR-SECRET", secretKey);
JSONObject json = new JSONObject();
json.put("version", "V2");
json.put("requestId", UUID.randomUUID().toString());
json.put("timestamp", System.currentTimeMillis());
JSONObject image = new JSONObject();
image.put("format", "jpg");
image.put("name", "demo");
JSONArray images = new JSONArray();
images.put(image);
json.put("images", images);
String postParams = json.toString();
con.connect();
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
long start = System.currentTimeMillis();
File file = new File(imageFile);
writeMultiPart(wr, postParams, file, boundary);
wr.close();
int responseCode = con.getResponseCode();
BufferedReader br;
if (responseCode == 200) {
br = new BufferedReader(new InputStreamReader(con.getInputStream()));
} else {
br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
}
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = br.readLine()) != null) {
response.append(inputLine);
}
br.close();
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
private static void writeMultiPart(OutputStream out, String jsonMessage, File file, String boundary) throws
IOException {
StringBuilder sb = new StringBuilder();
sb.append("--").append(boundary).append("\r\n");
sb.append("Content-Disposition:form-data; name=\"message\"\r\n\r\n");
sb.append(jsonMessage);
sb.append("\r\n");
out.write(sb.toString().getBytes("UTF-8"));
out.flush();
if (file != null && file.isFile()) {
out.write(("--" + boundary + "\r\n").getBytes("UTF-8"));
StringBuilder fileString = new StringBuilder();
fileString
.append("Content-Disposition:form-data; name=\"file\"; filename=");
fileString.append("\"" + file.getName() + "\"\r\n");
fileString.append("Content-Type: application/octet-stream\r\n\r\n");
out.write(fileString.toString().getBytes("UTF-8"));
out.flush();
try (FileInputStream fis = new FileInputStream(file)) {
byte[] buffer = new byte[8192];
int count;
while ((count = fis.read(buffer)) != -1) {
out.write(buffer, 0, count);
}
out.write("\r\n".getBytes());
}
out.write(("--" + boundary + "--\r\n").getBytes("UTF-8"));
}
out.flush();
}
}
import requests
import uuid
import time
import json
api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'
request_json = {
'images': [
{
'format': 'jpg',
'name': 'demo'
}
],
'requestId': str(uuid.uuid4()),
'version': 'V2',
'timestamp': int(round(time.time() * 1000))
}
payload = {'message': json.dumps(request_json).encode('UTF-8')}
files = [
('file', open(image_file,'rb'))
]
headers = {
'X-OCR-SECRET': secret_key
}
response = requests.request("POST", api_url, headers=headers, data = payload, files = files)
print(response.text.encode('utf8'))
<?php
$client_secret = "YOUR_SECRET_KEY";
$url = "YOUR_API_URL";
$image_file = "YOUR_IMAGE_FILE";
$params->version = "V2";
$params->requestId = uniqid();
$params->timestamp = time();
$image->format = "jpg";
$image->name = "demo";
$images = array($image);
$params->images = $images;
$json = json_encode($params);
$boundary = uniqid();
$is_post = true;
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, $is_post);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$post_form = array("message" => $json, "file" => new CURLFILE($image_file));
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_form);
$headers = array();
$headers[] = "X-OCR-SECRET: ".$client_secret;
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
$err = curl_error($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close ($ch);
echo $status_code;
if($status_code == 200) {
echo $response;
} else {
echo "ERROR: ".$response;
}
?>
application/json 요청 예제
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;
import org.json.JSONArray;
import org.json.JSONObject;
public class OCRGeneralAPIDemo {
public static void main(String[] args) {
String apiURL = "YOUR_API_URL";
String secretKey = "YOUR_SECRET_KEY";
try {
URL url = new URL(apiURL);
HttpURLConnection con = (HttpURLConnection)url.openConnection();
con.setUseCaches(false);
con.setDoInput(true);
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json; charset=utf-8");
con.setRequestProperty("X-OCR-SECRET", secretKey);
JSONObject json = new JSONObject();
json.put("version", "V2");
json.put("requestId", UUID.randomUUID().toString());
json.put("timestamp", System.currentTimeMillis());
JSONObject image = new JSONObject();
image.put("format", "jpg");
image should be public, otherwise, should use data
FileInputStream inputStream = new FileInputStream("YOUR_IMAGE_FILE");
byte[] buffer = new byte[inputStream.available()];
inputStream.read(buffer);
inputStream.close();
image.put("data", buffer);
image.put("name", "demo");
JSONArray images = new JSONArray();
images.put(image);
json.put("images", images);
String postParams = json.toString();
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(postParams);
wr.flush();
wr.close();
int responseCode = con.getResponseCode();
BufferedReader br;
if (responseCode == 200) {
br = new BufferedReader(new InputStreamReader(con.getInputStream()));
} else {
br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
}
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = br.readLine()) != null) {
response.append(inputLine);
}
br.close();
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
}
import requests
import uuid
import time
import base64
import json
api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'
with open(image_file,'rb') as f:
file_data = f.read()
request_json = {
'images': [
{
'format': 'jpg',
'name': 'demo',
'data': base64.b64encode(file_data).decode()
}
],
'requestId': str(uuid.uuid4()),
'version': 'V2',
'timestamp': int(round(time.time() * 1000))
}
payload = json.dumps(request_json).encode('UTF-8')
headers = {
'X-OCR-SECRET': secret_key,
'Content-Type': 'application/json'
}
response = requests.request("POST", api_url, headers=headers, data = payload)
print(response.text)
<?php
$client_secret = "YOUR_SECRET_KEY";
$url = "YOUR_API_URL";
$image_file = "YOUR_IMAGE_FILE";
$params->version = "V2";
$params->requestId = "uuid";
$params->timestamp = time();
$image->format = "jpg";
$image->data = base64_encode(file_get_contents($image_file));
$image->name = "demo";
$images = array($image);
$params->images = $images;
$json = json_encode($params);
$is_post = true;
$ch = curl_init();
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, $is_post);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
$headers = array();
$headers[] = "X-OCR-SECRET: ".$client_secret;
$headers[] = "Content-Type:application/json; charset=utf-8";
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
$err = curl_error($ch);
$status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close ($ch);
echo $status_code;
if($status_code == 200) {
echo $response;
} else {
echo "ERROR: ".$response;
}
?>