Table of Contents

Search and identify target| POST /v2/search

Search for image targets, an image-based search and recognition interface.

Action

POST /v2/search

Authentication

Required

Http header

Content-Type : multipart/form-data

Authorization (only when using API Key Token authentication)

Request parameters

Field Type Required Description
image Multipart Yes Base64-encoded string of image content, supports JPG and PNG format images.
notracking String No "false" means returning trackingImage. "true" means only returning the detected targetId attribute without the tracking image. WebAR recommends including this to reduce request latency by default.

Token authentication request example

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

Signature authentication request example

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
Important
  • Must use Client-end-URL as the recognition entry point, HTTPS uses port 8443
  • Set Connection: Keep-Alive in HTTP header to optimize repeated connection overhead

Response fields

Field Description
statusCode Status code 0 indicates correct authentication, more references Status codes
result Error message or target image information
timestamp Server-side time when response is returned. Using Unix timestamp format in milliseconds
result.targetId Unique ID of the target image
result.trackingImage Base64-encoded string of the tracking image
result.name Target name
result.size Recognition image width (unit cm). Height will be automatically calculated by the system based on your uploaded image. Recognition image size corresponds to the size of overlaid virtual content
result.meta Base64-encoded additional information, such as a string generated by base64-encoding a JSON string
result.type Fixed as ImageTarget
result.active "1" enabled, "0" disabled

Main response codes

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" }

Error codes

See Status codes and error codes

Request example

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"
}

Response example

  • If matched and recognized, returns structure as:

    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
    }
  • If no matching target image found, returns:

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