Table of Contents

Search target recognition | POST /v2/search

이미지로 이미지를 검색하는 타겟 인식 인터페이스입니다.

Action

POST /v2/search

인증

필요

Http Header

Content-Type : multipart/form-data

Authorization (API Key Token 인증 방식 사용 시만)

요청 매개변수

Field Type Required 설명
image Multipart Yes JPG 및 PNG 형식 이미지의 base64 인코딩 문자열
notracking String No "false" : trackingImage 트래킹 이미지 반환. "true" : 트래킹 이미지 없이 감지된 targetId 속성만 반환. WebAR 기본 권장 사항으로 요청 지연 시간을 줄임

Token 인증 요청 예시

curl -X POST -H "Authorization:xxx"  --form "image=@trackingImage.jpg;type=image/jpg"  --form appId=YOUR-APPID 
          https://<your-domain>-cn1.crs.easyar.com:8443/v2/search

서명 인증 요청 예시

curl -X POST --form "image=@trackingImage;type=image/jpg" 
              --form apiKey=YOUR-APIKEY  --form appId=YOUR-APPID 
              --form timestamp=1514736000000 
              --form signature=xxx 
          https://<your-domain>-cn1.crs.easyar.com:8443/v2/search
중요
  • Client-end-URL을 인식 엔트리로 사용해야 하며, https는 8443 포트입니다
  • 반복 연결 오버헤드 최적화를 위해 http header에 Connection: Keep-Alive 설정

반환 필드

필드 설명
statusCode 상태 코드 0은 인증 정상. 추가 참조 상태 코드
result 오류 메시지 또는 타겟 이미지 정보
timestamp 서버 응답 반환 시간. Unix 타임스탬프 형식(밀리초)
result.targetId 타겟 이미지 고유 ID
result.trackingImage 트래킹 이미지의 base64 인코딩 문자열
result.name 타겟 이름
result.size 인식 이미지 너비(cm). 높이는 업로드된 이미지에 따라 시스템 자동 계산
result.meta base64 인코딩된 메타 정보(예: JSON 문자열을 base64 인코딩한 문자열)
result.type 고정 값 ImageTarget
result.active "1" 활성화, "0" 비활성화

주요 반환 코드

응답 HTTPCODE 상태 결과
OK 200 0 result: { imageBody }
NO_RESULT 404 17 result: { message: "No result: there is no matching." }
NO_TARGET 500 18 result: { message: "Target not found: there is a matching but no target, please report this issue: IMAGE-UUID" }
TIMEOUT 408 19 result: { message: "Request timeout." }
OUT_OF_LIMIT 402 21 result: { message: "You have exceeded the limit of daily scanning." }
OUT_OF_QPS 200 21 result: { message: "Exceed your QPS limitation." }
RPC_ERROR 500 20 result: { message: "Error retrieving results." }
OTHER_ERROR 501 30 result: { message: "Other error occur: details" }

오류 코드

참조 상태 코드 및 오류 코드 목록

요청 예시

POST /search/ HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "timestamp": 1514736000000,
    "appKey": "test_app_key",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

반환 예시

  • 인식 성공 시 구조:

    HTTP/1.1 200 OK
    Content-Type: application/json
    {
        "statusCode": 0,
        "result": {
          "target": {
            "targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
            "trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
            "name": "easyar",
            "size": "5",
            "meta": "496fbbabc2b38ecs3460a...",
            "type": "ImageTarget",
            "modified":1514735000000
            "active":"1"，
            "trackableRate": 0,
            "detectableRate": 0,
            "detectableDistinctiveness"：0,
            "detectableFeatureCount": 0,
            "trackableDistinctiveness": 0,
            "trackableFeatureCount": 0,
            "trackableFeatureDistribution": 0,
            "trackablePatchContrast": 0,
            "trackablePatchAmbiguity": 0
          }
        },
        "timestamp": 1514736000000
    }
  • 매칭된 타겟 이미지 없을 시:

    HTTP/1.1 404 NOT FOUND
    Content-Type: application/json
    {
      "statusCode": 17,
      "result": {
        "message": "No result: there is no matching."
      }
    }