How To Use the Vuforia Web Services API

This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.

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.

The following 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.

Client Access Keys or Server Access Keys?

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 DB. And for generating printable instances of VuMarks using the VuMark Generation API with your VuMark DB, you will need a Pro License.

Target Management

• How To Add a Target
• How To Update a Target
• How To Delete a Target
• How To Retrieve a Target Record
• How To Check for Similar Targets
• How To Get a Target List for a Cloud Database

Reporting

• How To Retrieve a Target Summary Report
• How To Get a Database Summary Report

Debugging

• How To Interpret VWS API Result Codes

How To Add a Target

You can add targets to a Cloud Database using the Vuforia Web Services REST API by making an HTTP POST request to https://vws.vuforia.com/targets. The request header should include the authorization fields described in the article Vuforia Web Services guide, 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 targets.

Add a digital content payload

Vuforia Engine's Cloud Recognition service lets you add a digital content payload to your target. 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.

The developer CMS performs an HTTPS POST on https://vws.vuforia.com/targets. The header contains the usual HTTP header fields plus the Authorization field. The JSON body contains the new target information, including the image. The PostNewTarget.java sample shown below displays this code.

JSON body elements

The JSON body elements are listed in the following table:

JSON POST code 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"
}

JSON 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:

JSON response code example

HTTP/1.1 201 Created
Content-Type: application/json
{
  "result_code":"Success",
  "transaction_id":"e29b41550e8400d4a716446655440000",
  "target_id":"550b41d4a7164466554e8400e2949364"
}

How To Update a Target

To update a target in a database, the CMS must perform an HTTPS PUT on https://vws.vuforia.com/targets/{target_id}, with the following:

• A header that contains the usual HTTP header fields, plus the Authorization field
• The JSON body that contains the updated target information, including the image. The URL must replace {target_id} with the actual ID of the target returned when the target was created. This is shown in the UpdateTarget.java sample.

JSON body elements

The JSON body is defined in the following table:

JSON PUT code 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"
}

JSON 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.

JSON response code example

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result_code":"Success",
  "transaction_id":"550e8400e29b41d4a716446655482752"
}

How To Delete a Target

To delete a target in a database, the CMS needs to perform a HTTPS DELETE on https://vws.vuforia.com/targets/{target_id}, with a header that contains the usual HTTP header fields, plus the Authorization field, and no body.

The URL must have the {target_id} replaced with the actual ID of the target returned when the target was created. This code is shown in the DeleteTarget.java sample.

Confirm that a target's status value is success before trying to delete the target. Refer to How 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.

JSON DELETE code example

DELETE /targets/550e8400e29b41d34716446655834450  HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT 
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU

JSON 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:

JSON response code example

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result_code":"Success",
  "transaction_id":"550e8400e29b41d4a716446655482752"
}

How To Retrieve a Target Record

To get information on a specific target in a database, the CMS needs to perform a HTTPS GET on https://vws.vuforia.com/targets/{target_id}, (where {target_id} is replaced with the actual ID of the target), with the header containing the usual HTTP header fields plus the Authorization field. This is shown in the UpdateTarget.java sample.

JSON GET code example

GET /targets/550e8400e29b41d34716446655834450 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU

JSON response message

After the authentication has been confirmed, the Cloud Recognition Service returns a JSON message with the contents of the specified target. The developer's CMS should check to make sure 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:

The target_record body is listed in the following table:

JSON response code 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"
}

How To Check for Similar Targets

The developer's CMS performs an HTTPS GET on https://vws.vuforia.com/duplicates/{target_id}*.In addition to the usual HTTP header fields, the header also contains the Authorization field. The cloud service searches the database for similar images, including duplicate images as identified by 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.

JSON GET code example

GET /duplicates/550e8400e29b41d34716446655834450 
HTTP/1.1Host: vws.vuforia.comDate: Mon, 23 Apr 2012 12:45:19 
GMTAuthorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU

JSON 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:

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.

JSON response code example

HTTP/1.1 200 OK
Content-Type: application/json
{
  "similar_targets":[
    "550e8400e29b41d4a716446655447300",
    "578fe7fd60055cbc84c2d215066b7a9d"
  ]
}

JSON response message

After the authentication has been confirmed, the Cloud Recognition Service returns a JSON message with a list of all targets in the database. The CMS should check to make sure 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:

JSON response code example

HTTP/1.1 200 OK
Content-Type: application/json
{
  "result_code":"Success",
  "transaction_id":"550e8400e29440000b41d4a716446655",
  "results":[
    "00550e84e29b41d4a71644665555678",
    "578fe7fd60055a5a84c2d215066b7a9d"
  ]
}

How To Retrieve a Target Summary Report

To get a summary of a specific image in a database, the CMS must perform a HTTPS GET on https://vws.vuforia.com/summary/{target_id}, where {target_id} is replaced with the actual ID of the target. The header contains the usual HTTP header fields, plus the Authorization field.

JSON GET code example

GET /summary/550e846655447733400e29b41d4a7164 HTTP/1.1 
  Host: vws.vuforia.com 
  Date: Mon, 23 Apr 2013 12:45:19 GMT 
  Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU

JSON response message

After the authentication has been confirmed, the Cloud Recognition Service returns a JSON message with the contents of the specified target. The CMS should make sure 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:

Note: tracking_rating and reco_rating are provided only when status = success.

JSON response code 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
}

How To Get a Database Summary Report

To get a summary of images from a cloud database, you must ensure that the CMS performs a HTTPS GET on https://vws.vuforia.com/summary. The header contains the usual HTTP header fields, plus the Authorization field.

JSON GET code example

GET /summary  HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2013 12:45:19 GMT
Authorization: VWS df8d23140eb443505c0661c5b58294ef472baf64:jHX6oLeqTXpynyqcvVC2MSHarhU

JSON response message

After the authentication has been confirmed, the Cloud Recognition Service returns a JSON message with the contents of the specified target. The CMS should check to make sure 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:

JSON response code 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
}

How To Interpret VWS API Result Codes

The following table lists the supported result_code, its corresponding HTTP status code, and a description of the result.