Search and identify target | POST /v2/search

Search for image targets and identify them through image-based search.

Action

POST /v2/search

Authentication

Required

Http header

Content-Type: multipart/form-data

HTTP Header: Authorization (when using API Key Token authentication)

Request parameters

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

Token authentication request example

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

Example of signature authentication request

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

• Always use Client-end-URL as the recognition entry point, HTTPS uses port 8443
• Set Connection: Keep-Alive in the HTTP header to optimize repeated connection overhead

Return fields

Field	Description
statusCode	Status code 0 indicates correct authentication. For more details, refer to status code
result	Error message or target image information
timestamp	Server-side time when the response is returned. Uses 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	Width of the recognition image (in cm). The height of the recognition image will be automatically calculated by the system based on the uploaded image. The size of the recognition image corresponds to the size of the 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" for enabled, "0" for disabled

Main return 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 Complete list of 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"
}

Return example

• If a hit is recognized, the returned structure is as follows:

    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 there is no matching target image, the return example is as follows:

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