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

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.

Target Management

Reporting

Debugging

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

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:

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

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

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.

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

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

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:

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

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

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

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"
}

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.

JSON GET code example

GET /duplicates/550e8400e29b41d34716446655834450 HTTP/1.1
Host: vws.vuforia.com
Date: Mon, 23 Apr 2012 12:45:19 
GMT
Authorization: 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:

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.

JSON response code example

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

JSON response message

A JSON object with a list of similar 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

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

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.

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
}

Get a Database Summary Report 

To get a summary of images from a cloud database, execute a GET request on https://vws.vuforia.com/summaryJSON 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

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 data

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
}

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