The Wikitude Cloud Recognition service is a cloud-based service provided by Wikitude, which recognizes images sent from Android and iOS apps using the Wikitude SDK. The recognized images are then tracked in the live camera feed and can be used for augmented reality experiences.
This documentation focuses on the RESTful API called Manager API, which is used to interact on a backend level with the Cloud Recognition service.
Target: An image and its associated extracted data that is used to recognize an image.
Target Collection: A group of
targetsthat are searched together. Think of it as a directory, which contains all your images you want to search. The Wikitude SDK can work with two different sorts of
- On-device Target Collection: a static
wtcfile containing the extracted data of your images. Can consist of up to 1,000 images.
- Cloud Target Collection: A target collection stored on the Wikitude server. See
- On-device Target Collection: a static
Cloud Archive: An archive stored on the server that is optimized for cloud-based recognition. It is generated from a
TargetCollectionand is used in combination with the Wikitude SDK
ImageTracker: Instead of analysing and computing the live camera feed directly on the device like the combination of
AR.TargetCollectionResource, the combination of
AR.CloudRecognitionServicewill send the image(s) taken by the camera to the Wikitude Cloud Recognition server. The server will then do the hard work of trying to match the image with your targets in the specified cloud archive. Beside the benefit of searching in large image database using the
AR.TargetCollectionResourcehas also a positive impact on the general performance in most cases. Especially when using a large target collection and on older devices.
Manager API: A RESTful web API allowing developers to interact with the Cloud Recognition server for managing
Cloud Archives. Only you as a developer uses this API. None of your users of your app will interact with this API.
Client API: The Client API is the interface between the Wikitude SDK and the Cloud Recognition Service. The API itself is encapsulated in the Wikitude SDK class
AR.CloudRecognitionServiceand not directly accessible. Calls on the client API are called
Region: Wikitude is providing several hosting locations for its Cloud Recognition services to cut down unwanted network latency. As a developer you need to choose on which
Regionyou and your customers want to operate.
Getting Started with the Cloud Recognition Service
Regional availability of Wikitude Cloud Recognition Service
As a developer using Wikitude Cloud Recognition Service you need to choose which server location you want to use for your projects. Wikitude operates several servers running Wikitude Cloud Recognition Service in different locations world-wide.
As the region servers are separated, content which is stored on one region server is only available on this particular server. Content is not synced across regions. You can choose from the following
The servers for each region have separate dedicated domain names and therefore different configurations.
|Region||Target Manager||Manager API||SDK Setting|
|Europe||targetmanager.wikitude.com||https://api.wikitude.com or https://api-eu.wikitude.com||
- Create a free Wikitude developer account or log-in if you are a returning developer
- Get the API tokens for the Manager API and the Client API to start your project. Read more on authentication
- Test the API for free using Wikitude's sample integrations
- Once you finished your integration, purchase a commercial token.
First Steps and General Usage
- Get familiar with the Manager API calls in the API Reference.
- Create a first Target Collection using the
Create Target Collectionendpoint and note down the ID of the Target Collection
- Create targets using the
Create Targetendpoint for that particular Target Collection
Generate a Cloud Archivefor your Target Collection
- Go to the Wikitude SDK and create an Android or iOS project
- Use the Client API token to authenticate your Android or iOS project
- Use your Target Collection ID to recognize images
For more information on the available endpoints and how to work with the Manager API see the workflow section.
Instead of creating a
TargetCollection, adding one or more
Targets, and generating a
Cloud Archive by calling the REST API, the Wikitude Targetmanager can be used to perform these steps (1-4) in the browser alternatively.
In case you would like to immediately test the API calls we recommend the tool Postman. It helps you to quickly construct the requests and analyze the responses.
The Cloud Recognition Service knows three authentication items, that you need in order to work with the service
Manager API token You need this token to authenticate yourself against the RESTful Manager API. The Manager API is used to create, add and delete targets and target collections. The token identifies your developer account. Calls to the Manager API do not count towards your quota limits.
Client API token You need this token to authenticate calls from the Wikitude SDK to the Cloud Recognition services. It again authenticates calls as legitimate. The token is bound to your developer account. Calls from the Wikitude SDK to the service with a wrong or missing token can't access your target collections.
Group ID This value helps us load-balancing your calls and provider a better service overall. The value was introduced with SDK 8.0 and is mandatory since then. It is part of the Client API and needs to be added to your tracker.
Authentication on the Manager API
The Manager API token must be added to each call towards the Wikitude Cloud Recognition Manager API. The token authenticates the user account that is using the API.
Authentication on the Client API
The Client API token and Group ID must be added to your app project using the Wikitude SDK. These tokens are needed additionally beside the SDK license key when working with the
Quota and Limits
General Upload Limit
The Wikitude Cloud Recognition 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
Limits for the Wikitude Cloud Recognition Service
There are two main limitations for the Wikitude Cloud Recognition service that you need to be aware of:
Targets Your token has a certain number of targets that you can upload and store on the cloud service under your developer account. The limit is always counted for your entire developer account and not for a single target collection. The service is not counting single uploads, but how many targets are currently stored in target collections under your account.
Scans Scans are in effect calls from the Wikitude SDK via the Client API to the Cloud Recognition servers. All commercial license come with an allowance of 1,000,000 scans per month per developer account. Note: When using Continuous Search mode multiple calls are made to the server.
Maximum Number of Targets in a Target Collection
A target collection can't exceed 50,000 targets.
Free Trial License for Cloud Recognition
Wikitude provides a trial token for each developer account to try out the Cloud Recognition for free. This trial token has set a quota limit that allows developers to try and test the functionality of the service. Limitations for trial accounts
- Targets: 50,000
- Scans: 1,000 per month
To get your trial token for the REST API, please visit the License page. The trial token is directly integrated into Wikitude Studio.
For production systems, we offer commercial licenses with various quota limits for purchase.