Documentation

Getting Started

The Targets API has been deprecated since 05 November 2016. This service will be shut down 30th April 2017. You can migrate to the Cloud Recognition API, which offers the same functionality. If you have questions contact sales@wikitude.com

What is the Targets API

One of the main functionalities of the Wikitude SDK is to track 2-dimensional images in the camera stream of the mobile device. To achieve this, the developer using the Wikitude SDK must feed the SDK with the targets (digital images) to be tracked.

To allow a smooth and high-quality tracking of targets, the digital images must be preprocessed before they are fed into the Wikitude SDK. This preprocessing step is called Target Conversion. The process transforms digital images (jpeg or png images) into Targets and adds them to a TargetCollection. The Wikitude Targets API offers a web-based API to perform exactly this processing step, to be able to automatize the Target Conversion.

In general the conversion can be done via three different tools:

1

Web Target Manager Tool

A browser based tool to convert your images to a wtc file. You can find the tool under: targetmanager.wikitude.com. You need your free developer account to log-in.

2

Targets API

A RESTful API to convert images. This documentation describes the Targets API in more detail

3

Targets Enterprise Script

A binary shell script available for Mac OS X and Linux converting images to target collections. Pleases contact Wikitude Sales team for technical requirements and pricing.

The following images describes the relationship between the above mentioned methods and the Wikitude Cloud Recognition Service, which is not scope of this documentation.

General Definitions

Wikitude Targets API is a web-based API that allows to convert digital images into TargetCollections that can later be used in the Wikitude SDK to track the images contained in the TargetCollection.

A TargetCollection is a binary file that contains all information to track the digital images. Internally, a target collection consists of multiple Targets. Each target represents a particular digital image that can be tracked by the Wikitude SDK. The file extension of a TargetCollection is .wtc (WikitudeTargetCollection).

Getting Started with the Targets API

  1. Create a free Wikitude developer account or log-in if you are a returning developer
  2. Get an API token for the Wikitude Targets API to start integration.
  3. Test the API for free using Wikitude's sample integrations
  4. Once you finished your integration, purchase a commercial token.

Authentication and Quota Limits

A token must be added to each call towards the Wikitude Targets API. The token authenticates the user account that is using the API. Usage is limited by quota limits.

Each token allows a certain number of uploaded images per quota period. Once this quota is exceeded, the Targets API will not allow the conversion of additional images and will return an error code (see respond codes).

General Upload Limit

The Wikitude Targets API will not accept images bigger than 1024kB (1 MB). Trying to upload images exceeding this file size will result in a HTTP status code 400 together with an error message FILE_SIZE_LIMIT_EXCEED.

Free Trial of Targets API

Wikitude provides a trial token for each user account to try out the Targets API for free. This trial token has set a quota limit that allows developers to try and test the functionality of the API.

To get your trial token, please visit My License page.

Commercial Quota

For production systems, we offer premium tokens with various quota limits for purchase .

Product Quota upload images Number of images per request
Targets API 100 100 no limit (API will report 100)
Targets API 1000 1000 no limit (API will report 1000)

Versioning

Every software product improves over time, and the Wikitude SDK is no exception to this. Over time, we have improved the tracking quality significantly. While we are always focusing on ensuring backwards compatibility between the Wikitude SDK and the generated target collections, older versions of the Wikitude SDK might not be able to use newer versions of target collections. Therefore, the Targets API allows the generation of target collections for different versions of the Wikitude SDK by specifying a version parameter.

The following table outlines what version of the Targets API must be used with which Wikitude SDK version:

Wikitude SDK Version Targets API Version Comments
3.x and below 1 (deprecated)
4.0 2 (deprecated)
4.1 3 Wikitude SDK 4.1 is backwards compatible also with Targets API version 1 and 2 but we strongly recommend version 3 due to performance improvements. Support for Wikitude SDK version 3.x and 4.0 will be removed.
5.x 3 only 5.x removes support for version 1 and 2. You need to use version 3 with SDK 5.x and later

Target Quality

The experienced tracking quality of a certain target is dependent on the quality of the original digital image used for the preprocessing. A guide on how to create targets that track well can be found here.