The Kantar TGI API makes it easier for you to take advantage of TGI’s unique capabilities as a cloud-based web service.
If you are developing a custom application/platform and need to integrate TGI Data, we can provide a number of APIs to assist you, depending on your specific requirements.
For example, we can provide you with a “Crosstab” API that allows you to specify TGI target audiences within your own application and obtain the corresponding aggregated sample size, weighted population and index from the underlying data.
Currently the Kantar TGI APIs are available only to existing TGI subscribers in certain territories. Please contact us if you need more information.
TGI API documentation will provide you with the information you need to use the TGI API in your own applications. The TGI API is a RESTful service returning JSON results, which provides methods for browsing the full range of variables available in a TGI survey and querying the TGI data. The available API methods and their use are explained below.
The starting point for all applications working with the TGI API is the TGI survey and wave. Use the following methods to get the survey and waves that you subscribe to. There are 2 API methods for accessing surveys:
The variables for a TGI Survey are organised into a classification structure called a dictionary. A TGI dictionary provides a hierarchical tree grouping individual questions and answers (variables) in a logical structure. The structure varies from Survey to Survey and as such care should be taken when making assumptions in code that rely on a given structure. There are 3 methods available for querying the dictionary structure:
As a TGI API user, you will also be given access to Target Export. Target export allows you to browse the TGI dictionary, create targets and export these targets in either JSON or text format. The export will provide you with the keywords you need to call the data from the TGI API. For further information on Target export, please speak to your TGI account manager or refer to the Target Export Quick Guide.
An individual question JSON object provides details of the available answers. Each answer is assigned a unique keyword which can be used to process the survey data.
Alternatively browse the dictionary using our Target Export App to get the unique keywords for the variables you would like to call.
There are 3 methods available for querying (processing) TGI data:| Description | Expression |
|---|---|
| All Men | DBSEXLME |
| All Men Aged 15-24 | (DBSEXLME) AND (DBAGE152) |
| All Men Aged 15-44 | DBSEXLME AND (DBAGE152 OR DBAGE253 OR DBAGE354) |
| Average Cinema visits among visitors. | MeanScoreNoNull(GLCIFNAW,5,GLCIF23M,2.5,GLCIF1AM,1,GLCIFM23,0.3,GLCIF23Y,0.2,GLCIFLOF,0.1) |
| Operator | Type | Action |
|---|---|---|
| AND | Binary | Bitwise Boolean logical AND |
| OR | Binary | Bitwise Boolean logical OR |
| XOR | Binary | Bitwise Boolean logical XOR |
| NOT | Unary | Bitwise Boolean logical NOT |
| () | Brackets for controlling order of precedence. | |
| MEANSCORE(<keyword>,<midpoint>,<keyword>,<midpoint>…) | Function | Calculates the arithmetic mean of a variable using mid-points assigned to each value. Denominator is total base. |
| MEANSCORENONULL(<keyword>,<midpoint>,<keyword>,<midpoint>…) | Function | Calculates the arithmetic mean of a variable using mid-points assigned to each value. Denominator is total base who have a value including zero. |
| MEANSCORENOZERO(<keyword>,<midpoint>,<keyword>,<midpoint>…) | Function | Calculates the arithmetic mean of a variable using mid-points assigned to each value. Denominator is total base who have a value greater than 0. |
| MEANSCORENOZERO(<keyword>,<midpoint>,<keyword>,<midpoint>…) | Function | Calculates the arithmetic mean of a variable using mid-points assigned to each value. Denominator is total base who have a value greater than 0. |
Only authorised client applications are allowed to make calls to the API. To call the API you must first have a valid API key. The API key is unique for each client and is valid for the duration of a valid TGI data subscription.
Each call must also be associated with a named user at the client. The userid will need to be sent along with each call to the API. The userid is generated by registering users with TGI against a specific API key. The User Id and API key will be supplied to you by the TGI client service team once you have been given access to the TGI API.
Every API request requires authentication via a pre-registered API key. This key will be provided to you once you have been given access to the TGI API. This key is unique and is associated with named users. As mentioned above, a valid key and a valid user id are required to make calls to the TGI API.
This guide uses the demo API account, which is free to use. The example calls provided have been pre-populated with the required key and user id.
Requests can be made from client-side applications but must originate from a pre-authorised web site or browser extension URL associated with a given API key. Each client-side call must include both a valid apikey and a valid userid.