Vuforia Query Web API | Vuforia Library

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 Query Web API performs a Cloud Recognition search within the Cloud database associated to the Client Access Keys provided in the Authorization header.

Authentication

All requests to the Web Query API need to be authenticated. The authentication scheme is described in the Vuforia Web API Authentication following the Vuforia Web Services (VWS) scheme. Follow the steps described in this article for Making API Calls while replacing the Server Access Keys server_access_key and server_secret_key with your Client Access Keys »server_secret_key and client_secret_key.

Submitting a Query

Perform an image recognition query by including the required requests listed below. Include in the request header both Authorization, date, and declaration of the content type. The request body can consist of three fields to submit your image recognition specifications on a query.

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

Authorization (required by authentication VWS protocol, see Authentication above).
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 KB for JPEG, 2MB for PNG.
The text fields shall be UTF-8 encoded.
The API accepts requests with unknown data fields, and ignore the unknown fields.
The API rejects requests with missing, malformed, out-of-range or incomplete data fields.

Query Request Body

Field	Content-Type	Type	Mandatory	Description
`image`	image/jpeg or image/png	Binary image file in jpg or png format	Yes	Query Image. See above notes for recommendations and maximum size.
`max_num_results`	text/plain	Int [1..10]	No	Indicates 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_data`	text/plain	String	No	Indicates 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 message

The returned response will contain query ID, list of matching targets, and whether the query was successful,

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 the 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 JSON body 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 the List of failure cases and returned values.

Query Response Body

Field	Type	Mandatory	Description
`query_id`	32-character String (UUID)	yes	A unique transaction id for this query.
`results`	List of Query Result Entry	Mandatory for successful queries, missing for failed queries.	A list of target matches, sorted by the internal recognition confidence.
`result_code`	String	yes	Result code indicating success ( Success ) or a specific type of failure of the request. See possible values for error cases below.

Query Result Entry

Field	Type	Mandatory	Description
`target_id`	32-character String (UUID)	yes	UUID of the target
`target_data`	Target Data record	No (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

Field	Type	Mandatory	Description
`name`	String	yes	The name of the target
`application_metadata`	String	yes	The application metadata associated to the target (user-provided). Encoded in base64.
`target_timestamp`	Int	yes	Timestamp when target was created/updated in seconds since Jan 1, 1970 GMT (Unix time). Note that this is an unsigned 32-bit integer.

Learn More

Vuforia Web Services API

Vuforia Web API Authentication

Cloud Targets Web API