Cloud Targets Web API¶

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.

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 Image 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¶

POST /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¶

HTTP/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¶

PUT /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¶

HTTP/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¶

DELETE /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
`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¶

HTTP/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¶

GET /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 Image 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¶

HTTP/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¶

GET /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¶

HTTP/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¶

GET /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 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
results	target_id [0..unbounded]	Yes	List of target IDs for the target in the developer project

Response example¶

HTTP/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¶

GET /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
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

HTTP/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¶

GET /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_threshold	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

HTTP/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

Learn More¶

Vuforia Web Services API

Vuforia Web Query API

Vuforia Web API Authentication

Cloud Targets Web API¶

Target Management¶

Reporting¶

Debugging¶

Authentication¶

Add a Target¶

JSON body elements¶

POST example¶

Response message¶

Response example¶

Update a Target¶

PUT example¶

Response message¶

Response example¶

Delete a Target¶

DELETE example¶

Response message¶

Response example¶

Retrieve a Target Record¶

GET example¶

Response message¶

Response example¶

Check for Similar Targets¶

GET example¶

Response message¶

Response example¶

List Targets¶

GET example¶

Response message¶

Response example¶

Retrieve a Target Summary Report¶

GET example¶

Response message¶

Get a Database Summary Report¶

GET example¶

Response message¶

VWS API Result Codes¶

Learn More¶