How To Perform an Image Recognition Query

The Vuforia Web Query API enables you to match a submitted image against your Cloud databases. It receives a single image, via HTTP, and returns a list of any matching results.

The Web Query operation performs a Cloud Recognition search within the Cloud database specified by the query keys provided in the authentication header.
 

Authentication

All requests to the Web Query API need to be authenticated. The authentication scheme is described in this section.
Authentication is uses a server-access key pair in the form of {server_access_key, server_secret_key} which authenticates the user and authorizes their access a Cloud database for image matching. You can find this key pair in the Database Access Keys tab for your Cloud database.
 
The standard HTTP Authorization header is used to pass authentication information. It has the following form:
Authorization: VWS {server_access_key}:{Signature}
 
Where:
  • VWS stands for Vuforia Web Service.
  • The server_access_key identifies the server_secret_key that was used to compute the signature, and the Cloud database for which the request is.
  • The signature is a hash-based Message Authentication Code (MAC) [2]. Following is pseudo-grammar that illustrates the construction of the signature (\n means the Unicode code point U+000A).
 
Signature = Base64(HMAC-SHA1(server_secret_key, StringToSign ) ) );

StringToSign = 
  HTTP-Verb + "\n" +
  Content-MD5 + "\n" +
  Content-Type + "\n" +
  Date + "\n" +
  Request-Path;
 
Where:
  • HTTP-Verb: The HTTP method used for the action. Example:GET, POST, etc.
  • Content-MD5: The hexadecimal MD5 hash of the whole request body (from first boundary to last one, including the boundary itself). Use an empty string for request types without request body, i.e. MD5(“”).
  • Content-Type: the content-type of the request body (e.g. multipart/form-data). Use an empty string for request types without request body.
  • Date: Current date, e.g.:Sun, 22 April 08:49:37 GMT. The data format must exactly match the Date that is sent in the ‘Date’ header.
Notes:
  • A valid time-stamp (using the HTTP Date header) is mandatory for authenticated requests.
  • TLS 1.2 or above with server authentication is required for the API. Plain HTTP requests and requests sent to another port than 443 will be rejected.

Request Method: POST
Request URL: cloudreco.vuforia.com/v1/query
Request Headers:

  • Authorization (required by authentication protocol, see Authentication)
  • Content-Type (multipart/form-data)
  • Optional: Accept (application/json)
  • Date (required by authentication protocol)
Request Body: The Request body is formatted as multipart/form-data. The expected fields are listed in Table 2: Query Request Body.
Notes:
  • Recommended image settings (best recognition performance and latency): JPEG, 640 pixels on the longer image side, compression quality 50-75
  • Maximum image size: 2.1 MPixel. 512 KiB for JPEG, 2MiB for PNG
  • The text fields shall be UTF-8 encoded.
  • The API rejects requests with malformed or out-of-range or incomplete data.
  • The API accepts requests with unknown data fields, and ignore the unknown fields.
  • The API rejects requests if a mandatory data field is missing.

Query Request Body

FieldContent-TypeTypeMandatoryDescription
imageimage/jpeg or image/pngBinary image file in jpg or png formatYesQuery Image. See notes for recommendations and maximum size.
max_num_resultstext/plainInt [1..10]NoIndicates the maximum number of matching targets to be returned. Default value is 1 (return the best match, if any targets match at all)
include_target_datatext/plainStringNoIndicates if ‘target_data’ records shall be returned for the matched targets. Accepted values are “top” (default value, only return target_data for top ranked match), “none” (return no target_data), “all” (for all matched targets)
     

Response Headers:
  • Content-type (application/json or other for some failure cases with unspecified body)
Response Status Code:
  • Success case: 200 OK
  • Failure cases: 4xx and 5xx Status codes (see error cases, Table 6: List of failure cases and returned values)
Response Body:
  • Success case: JSON object with fields shown in Table 3: Query Response Body
  • Failure cases: Depending on the type of failure there will be either a JSONbody according to Table 3: Query Response Body (without ‘results’ field), or there will be an arbitrary body (or even no body at all). For details, see Table 6: List of failure cases and returned values

Query Response Body

FieldTypeMandatoryDescription
query_id32-character String (UUID)yesA unique transaction id for this query.
resultsList of “Query Result Entry”Mandatory for successful queries, missing for failed queries.A list of target matches, sorted by the internal recognition confidence.
result_codeStringyesResult code indicating success (“Success”) or a specific type of failure of the request. See possible values for error cases below.
    

Query Result Entry

FieldTypeMandatoryDescription
target_id32-character String (UUID)yesUUID of the target
target_data“Target Data” recordNo (see description)“Target Data” record describing the matched target. Whether or not this field is returned depends on the ‘include_target_data’ parameter in the request.
    

Target Data

FieldTypeMandatoryDescription
nameStringyesThe name of the target
application_metadataStringyesThe application metadata associated to the target (user-provided). Encoded in base64.
target_timestampIntyesTimestamp when target was created/updated in seconds since Jan 1, 1970 GMT (Unix time). Note that this is an unsigned 32-bit integer.