Table of Contents

搜尋識別目標| POST /v2/search

搜尋影像目標，以圖搜圖識別介面。

Action

POST /v2/search

認證

需要

Http header

Content-Type : multipart/form-data

Authorization (僅當採用 API Key Token 方式認證)

請求參數

Field Type Required Description
image Multipart Yes 影像內容的 base64 編碼字串，支援 JPG 和 PNG 格式影像。
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" 停用

主要返回碼

Response HTTPCODE Status Result
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."
      }
    }