The Vuforia Web Services API enables you to query, upload, and manage images in Cloud Databases and to obtain reports on your targets and databases using a REST based API via HTTP. You can also use VWS to generate printable instances of VuMarks using the VuMark Generation API.
This article explains how to use the VWS API to perform various types of operations. We also provide VWS Samples (Java & PHP) to illustrate the best practices for a developer to follow when using the VWS.
Target Management
- Add a Target
- Update a Target
- Delete a Target
- Retrieve a Target Record
- Check for Similar Targets
- List Targets
Reporting
Debugging
Authentication
All requests to the Cloud Targets Web API need to be authenticated using the Vuforia Web Services (VWS) signature scheme described in the Vuforia Web API Authentication.
For managing Cloud targets using the VWS API, you will need to use the Server Access Keys associated with your Cloud DB. For performing an Image Recognition Query, you will need to use the Client Access Keys associated with your Cloud Database.
See the Vuforia Web API Authentication for more info.
Add a Target
You can add targets to a Cloud Database using the Vuforia Web Services REST API by making a POST request to https://vws.vuforia.com/targets. The request should include the Authorization header described in the article Vuforia Web API Authentication, and it should declare an application/JSON content type. The body of the request must be a JSON object that defines the properties of the target.
The image file that you upload must fit within the supported format and be maximum 2MB. See also the other requirements for images described in Image Targets.
You can include up to 1 MB of base 64 encoded content as metadata attached to the target's search result. Examples of this content could be images or mobile-optimized 3D models. This feature lets you host your content with your targets in the Cloud Recognition service.
JSON body elements
The JSON body elements are listed in the following table:
Field name |
Type |
Mandatory |
Description |
name |
String [1 - 64] |
Yes |
Name of the target, unique within a database |
width |
Float |
Yes |
Width of the target in scene unit |
image |
Base64 encoded binary image file in JPG or PNG format |
Yes |
Contains the base64 encoded binary recognition image data |
active_flag |
Boolean |
No |
Indicates whether or not the target is active for query |
application_metadata |
Base64 encoded data |
No |
The base64 encoded application metadata associated with the target |
POST example
1234567891011CopyPOST /targets HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2012 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Content-Type: application/json
{
"name":"tarmac",
"width":32.0,
"image":"0912ba39x...",
"application_metadata":"496fbb6532b3863460a984de1d980bed5ebcd507"
}
Response message
The response contains the target ID of the returned target. The result_code
field should indicate Created
; if not, an error has occurred. The returned JSON body structure is listed in the following table:
Field |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
target_id |
32-character String (UUID) |
Yes |
ID of the target |
Response example
1234567CopyHTTP/1.1 201 Created
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"e29b41550e8400d4a716446655440000",
"target_id":"550b41d4a7164466554e8400e2949364"
}
Update a Target
To update a target in a database, perform a PUT request on https://vws.vuforia.com/targets/{target_id}
The JSON body is defined in the following table:
Field name |
Type |
Mandatory |
Description |
name |
String [1 - 64] |
No |
Name of the target, unique within a database |
width |
Float |
No |
Width of the target in scene unit |
image |
Base 64 encoded binary image file in JPG or PNG format |
No |
Contains the base 64 encoded binary recognition image data |
active_flag |
Boolean |
No |
Indicates whether or not the target is active for query |
application_metadata |
Base 64 encoded data |
No |
The base 64 encoded application metadata associated with the target |
PUT example
123456789101112CopyPUT /targets HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Content-Type: application/json
{
"name":"tarmac",
"width":32.0,
"image":"0912ba39x...",
"active_flag":true,
"application_metadata":"496fbb6532b3863460a984de1d980bed5ebcd507"
}
Response message
The response contains the ID of the resulting target. Confirm that the status is Success; if not, an error has occurred. The resulting JSON body structure is listed in the following table.
Field |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
Response example
123456CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"550e8400e29b41d4a716446655482752"
}
Delete a Target
To delete a target in a database, perform a DELETE request on https://vws.vuforia.com/targets/{target_id}. Confirm that a target's status value is success
before trying to delete the target. Refer to Retrieve a Target Record for details on how to query the target status using GET /targets/{target_id}
. The value of active_flag
and rating are not valid until the status value is either success
or failed
.
NOTE: Targets in a processing status cannot be deleted.
DELETE example
1234CopyDELETE /targets/550e8400e29b41d34716446655834450 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
The response contains the status of the deletion. Confirm that the status value is success. Otherwise an error has occurred. The following table shows the structure of the returned JSON body:
Field |
Type |
Mandatory |
Description |
|
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
|
32-character String (UUID) |
Yes |
ID of the transaction |
Response example
123456CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"550e8400e29b41d4a716446655482752"
}
Retrieve a Target Record
To get information on a specific target, perform an GET request on https://vws.vuforia.com/targets/{target_id}.
Note that the number of requests is limited to 45 per seconds.
GET example
1234CopyGET /targets/550e8400e29b41d34716446655834450 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
After the authentication was confirmed, the Cloud Recognition Service returns a JSON message with the contents of the specified target. The client should check that the result_code
indicates Success. Otherwise, there was a problem retrieving the list.
The structure for the returned JSON body is listed in the following table:
Field name |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
target_record |
targetRecord |
Yes |
Contains a target record at the TMS |
status |
String [1-64] |
Yes |
Status of the target; current supported values are processing, success, and failed |
The target_record
body is listed in the following table:
Field name |
Type |
Mandatory |
Description |
target_id |
32-character String (UUID) |
Yes |
Target_id of the target |
active_flag |
Boolean |
No |
Indicates whether or not the target is active for query; the default is true |
name |
String [1-64] |
Yes |
Name of the target; unique within a database |
width |
Float |
Yes |
Width of the target in scene unit |
tracking_rating |
Int [0 - 5] |
Yes |
Rating of the target recognition image for tracking purposes |
reco_rating |
string |
No |
Unused. Always contains an empty string |
Response example
123456789101112131415CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"e29b41550e8400d4a716446655440000",
"target_record":{
"target_id":"550b41d4a7164466554e8400e2949364",
"active_flag":true,
"name":"tarmac",
"width":100.0,
"tracking_rating":4,
"reco_rating":""
},
"status":"Success"
}
Check for Similar Targets
Execute a GET request on https://vws.vuforia.com/duplicates/{target_id}. to search the database for duplicate and similar images of a given target_id. Some other things to consider with the similar target check:
- The duplicate check can be called as soon as a target's upload action has finished using POST or PUT. The target referenced by target_id does not have to be in active state to perform the similar target check.
- If a target is explicitly inactivated through the VWS API (or through the Target Manager), then the target is no longer taken into account for the similar target check.
- If the requested target does not exist, the service returns an UnknownTarget (404) error in the POST response body.
- Requests are limited to 10 per seconds.
GET example
12345CopyGET /duplicates/550e8400e29b41d34716446655834450 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2012 12:45:19
GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
The response returns a list of similar and/or duplicate targets, if any are available, sorted by the internal confidence in similarity. The maximum number of similar targets is 16. The resulting JSON body is structured as follows:
Field Name |
Type |
Mandatory |
Description |
similar_targets |
targetID [0..16] |
Yes |
List of similar and/or duplicate targets for a given target_id, sorted by the internal confidence in similarity |
If the successful answer does not contain duplicates, it means that no similar targets were found. If the requested target does not exist, the UnknownTarget (404) error is returned in the response body.
Response example
12345678CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"similar_targets":[
"550e8400e29b41d4a716446655447300",
"578fe7fd60055cbc84c2d215066b7a9d"
]
}
List Targets
In order to retrieve the target list for a cloud database, perform a GET request on https://vws.vuforia.com/targets.
The list operation is limited to 1 request per minute and fails for databases with more than 1 million images. If you need a target list for databases having more than 1 million images, please reach out to us via the Vuforia Production Support online form.
GET example
1234CopyGET /targets HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2012 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
A JSON object with a list of targets in the database is returned. The client should check that the result_code
indicates Success
. Otherwise, there was a problem retrieving the list.
The structure for the returned JSON message is listed in the following table:
Field |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
results |
target_id [0..unbounded] |
Yes |
List of target IDs for the target in the developer project |
Response example
12345678910CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"550e8400e29440000b41d4a716446655",
"results":[
"00550e84e29b41d4a71644665555678",
"578fe7fd60055a5a84c2d215066b7a9d"
]
}
Retrieve a Target Summary Report
To get a summary of a specific image in a database, perform a GET request on https://vws.vuforia.com/summary/{target_id}.
GET example
1234CopyGET /summary/550e846655447733400e29b41d4a7164 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
A JSON object with the contents of the specified target is returned. The client should check that the result_code indicates Success
. Otherwise there was a problem retrieving the list.
The structure for the returned JSON body is listed in the following table:
Field name |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
database_name |
String [1 - 64] |
Yes |
Name of the database |
target_name |
String [1 - 64] |
Yes |
Name of the target |
upload_date |
Date |
Yes |
Date of the upload (specified as YYYY-MM-DD) |
active_flag |
Boolean |
Yes |
Indicates whether or not the target is active for query; default is true |
status |
String [1- 64] |
Yes |
Status of the target; current supported values are processing, success, and failure |
tracking_rating |
Int [0 - 5] |
No* |
Rating of the target recognition image for tracking purposes |
reco_rating |
String |
No* |
Unused. Always contains an empty string |
total_recos |
Int |
No* |
|
current_month_recos |
Int |
No* |
|
previous_month_recos |
Int |
No* |
|
NOTE: tracking_rating
and reco_rating
are provided only when status returns success
.
Response example
12345678910111213141516CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"d4a716446655440663390e8400e29b41",
"database_name":"RecoTest",
"target_name":"tarmac",
"upload_date":"2012-03-31",
"active_flag":true,
"status":"success",
"tracking_rating":4,
"reco_rating":"",
"total_recos":0,
"current_month_recos":0,
"previous_month_recos":0
}
Get a Database Summary Report
To get a summary report for a cloud database, execute a GET request on https://vws.vuforia.com/summary
GET example
1234CopyGET /summary HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU
Response message
A JSON object with the database summary report is returned. The client should check that the result_code
indicates Success
. Otherwise there was a problem retrieving the list.
The structure for the returned JSON body is as listed in the following table:
Field name |
Type |
Mandatory |
Description |
result_code |
String [1 - 64] |
Yes |
One of the VWS API Result Codes |
transaction_id |
32-character String (UUID) |
Yes |
ID of the transaction |
name |
String [1 - 64] |
Yes |
Name of the database |
active_images |
uint32 |
Yes |
Total number of images with active_flag = true, and status = success for the database |
inactive_images |
uint32 |
Yes |
Total number of images with active_flag = false, and status = success for the database |
failed_images |
uint32 |
Yes |
Total number of images with status = fail for the database |
reco_treshold | int | No* | Number of allocated recos per month as specified by the license associated to this database |
total_recos | int | No* | Total amount of recos in this database lifetime |
current_month_recos | int | No* | Number of recos in the current month |
previous_month_recos | int | No* | Number of recos in the previous month |
Response example
12345678910111213CopyHTTP/1.1 200 OK
Content-Type: application/json
{
"result_code":"Success",
"transaction_id":"00e2550e849b41d4a755440000164466",
"name":"RecoTest",
"active_images":3,
"inactive_images":0,
"failed_images":0,
"reco_threshold":1000,
"total_recos":1600,
"current_month_recos":100,
"previous_month_recos":200}
VWS API Result Codes
The following table lists the supported result_code, its corresponding HTTP status code, and a description of the result.
result_code |
HTTP status code |
Description |
Success |
OK (200) |
Transaction succeeded |
TargetCreated |
Created (201) |
Target created (target POST response) |
AuthenticationFailure |
Authentication failure (401) |
Signature authentication failed |
RequestTimeTooSkewed |
Forbidden (403) |
Request timestamp outside allowed range |
TargetNameExist |
Forbidden (403) |
The corresponding target name already exists (target POST/PUT response) |
RequestQuotaReached |
Forbidden (403) |
The maximum number of API calls for this database has been reached. |
TargetStatusProcessing |
Forbidden (403) |
The target is in the processing state and cannot be updated. |
TargetStatusNotSuccess |
Forbidden (403) |
The request could not be completed because the target is not in the success state. |
TargetQuotaReached |
Forbidden (403) |
The maximum number of targets for this database has been reached. |
ProjectSuspended |
Forbidden (403) |
The request could not be completed because this database has been suspended. |
ProjectInactive |
Forbidden (403) |
The request could not be completed because this database is inactive. |
ProjectHasNoApiAccess |
Forbidden (403) |
The request could not be completed because this database is not allowed to make API requests. |
UnknownTarget |
Not Found (404) |
The specified target ID does not exist (target PUT/GET/DELETE response) |
BadImage |
Unprocessable Entity (422) |
Image corrupted or format not supported (target POST/PUT response) |
ImageTooLarge |
Unprocessable Entity (422) |
Target metadata size exceeds maximum limit (target POST/PUT response) |
MetadataTooLarge |
Unprocessable Entity (422) |
Image size exceeds maximum limit (target POST/PUT response) |
DateRangeError |
Unprocessable Entity (422) |
Start date is after the end date |
Fail |
Unprocessable Entity (422) |
The request was invalid and could not be processed. Check the request headers and fields. |
TooManyRequests | Too Many Requests (429) | Too many requests per second. Maximum requests are limited to 15 per second with a few exceptions for GET /targets/ and GET /duplicates/. |
Fail |
Internal Server Error (500) |
The server encountered an internal error; please retry the request |