The TIOBE TICS Web API is the public programming interface for the TICS viewer. It exposes the same metric data that the viewer uses, allowing you to integrate TICS data in your own management dashboard or reporting software.

The API follows a RESTful design, meaning that you use the HTTP protocol to request data. By using the HTTP protocol, you are not bound to a particular programming language or platform to consume the API. We recommend using a standard HTTP client library that is available for your platform.

HTTP Requests

Data is queried using a HTTP GET request on a particular URL. You can use a standard browser to experiment with the API. For example, to get the last measured value for the TIOBE Quality Indicator metric for project "" with branch "", use the following URL:


The URL has the following variables:

The host name and port on which the TICS viewer runs.
The "section" that you want to request data for. In a default TICS installation there is only one section named TICS.
Indicates which version of the API you want to use. The version number is increased every time we have to make a backwards incompatible change to the API. This ensures that consumers of the old API do not break. New fields will be added to the API without increasing the version number, as this will not break existing consumers.
The name of the API that you want to query. In this case the Measure API is consulted, which provides metric value data.
The part after '?' is called the query-string part of the URL and contains the API parameters. Each parameter is specified using a name=value pair. Multiple parameters are joined using '&'. Unrecognized parameters are silently ignored.

URLs should be encoded using percent encoding (%20 for spaces, %2B for +, etc).

HTTP Response

If the request HTTP is valid and can be performed without problems, the API will return a HTTP status 200 response. The body of this response contains the requested data in JSON format. For the call above, this will look something like this:

  "data": [
      "value": 77.39341858450899,
      "formattedValue": "77.39%",
      "letter": "C"
  "metrics": [
      "expression": "tqi",
      "fullName": "TQI"
  "nodes": [
      "name": "trunk",
      "fullPath": ""
  "dates": [
"Data", "metrics", "nodes", etc. are JSON object fields. The response is guaranteed to contain at least these fields, but might contain more when we add functionality to the API later. As such, you should not attempt to interpret the response by assuming the value you need is on a certain line or column number, or by using regular expressions! You should also not assume that the fields of the JSON object are in a specific order. You should only interpret the response by running it through a JSON parser and accessing the documented fields of the resulting JSON object. We recommend using a standard library for JSON parsing, such as Gson for Java, or the json library in Python.

If something went wrong, the status code 400 is used to indicate "expected errors". An example of an expected error is when you request data for a non-existent project. Status code 500 is used for unexpected errors. In this case, contact us and provide the resulting stack trace.

API Endpoints

The available API endpoints are now discussed in detail. For each endpoint we describe the input parameters that it accepts and the fields in the JSON output. Multiple values for an input parameter can be separated using commas (,). Parameter names and values are case-sensitive.

Currently there are three public endpoints available:

Measure API

Use the Measure API to obtain (aggregated) metric values for specific folders or files at a specific date. Use the following URL:

The input parameters are:
Parameter Value Required Description
metrics A metric expression yes

A list of metrics for which you want to obtain data. For example, use metrics=tqi to obtain the metric values for the TIOBE Quality Indicator or metrics=loc,eloc to get the metric values for both the Lines of Code and Effective Lines of Code metrics.

A list of commonly used metrics can be found here. Unrecognized identifiers will be silently ignored: the response will not contain any data for it and no error will be generated.

nodes A paths expression yes

A list of paths for which you want obtain data. A path identifies a node in the tree representing your archive's hierarchy of folders and source files. For example, use nodes=HIE:////path/to/file.cpp to get data for file.cpp in branch "" in . More information about path literals is found here.

Data is automatically aggregated when a folder path is specified, using the metric's intrinsic aggregation function. You cannot control the aggregation function via the API. As it does usually not make sense to aggregate data over branches, it is not possible to query data at project level (e.g., nodes=HIE://).

dates date expression no

One or more dates for which you want to obtain data. If omitted, the last TICS measurement date (for the respective project) is used. The requested date does not need to coincide with a measurement date. In that case, the metric value for the immediately preceding measurement date will be returned.

The date format follows the ISO 8601 standard: YYYY-MM-DDThh:mmTZD, where TZD is the time zone designator (Z for UTC or +hh:mm or -hh:mm). For example, use dates=2013-02-01T00:00Z to get data for February 1, 2013 at midnight in the UTC time zone. It is recommended that you specify the time zone explicitly. If the time zone is omitted, the time is considered local to the server on which the TICS Viewer runs.

The JSON output fields are:
Field Description

An array of metric objects for which data is available in the data field. These objects have the following fields:

expression The unique identifier for this metric. Example: loc.
fullName The human-readable name for this metric, as it is displayed in the viewer. Example: Lines of Code.

An array of path objects for which data is available in the data field.

A path object denotes a node in a particular view on the source tree and has the following fields:

name The simple name of the path, e.g. file.cpp
fullPath The full path name, e.g. HIE:////path/to/file.cpp
Limitation: You cannot query data for paths referring to multiple projects. You need to split the API call up so that each call refers to only one project.

An array of stringified timestamps for which data is available in the data field, in ISO 8601 format. The time zone used is that of the viewer's machine. Example: 2014-02-07T16:19:09.000+01:00. If the optional "dates" input parameter was omitted, this array contains a single item: the timestamp of the last TICS run for the respective project.


An array containing the requested metric value objects. These objects have the following fields:

value The unformatted metric value as a JSON number. Depending on the metric, this will be an integer (e.g. for lines of code) or a floating point value (e.g. for average cyclomatic complexity).
letter If applicable, contains the TQI score (A, B, C, D, E, or F), otherwise null.
formattedValue The formatted metric value is a string representation of the metric value. It uses the same formatting as the viewer and can therefore change between versions. It can contain HTML, for instance for delta metrics or when the metric value could not be determined due to analysis errors. Therefore, do not attempt to interpret the value or do computations with it. Use the value for that instead.
The data array contains a metric value object per metric, date, and node combination, and thus contains |metrics| × |dates| × |nodes| elements. Pseudo-code for iterating over the data array:
var idx = 0;
foreach(metric in json.metrics) {
    foreach(date in json.dates) {
        foreach(node in json.nodes) {
            var metricValue = json.data[idx];
            console.log('Value for metric %s, node %s at %s is %s', metric.fullName, node.fullPath, date, metricValue.formattedValue);
            idx += 1;
Note that you should iterate over the actual objects present in the metrics, dates, and nodes fields of the response, and not over the input parameters.

Path Expressions

The simplest way to provide paths to the nodes parameter of an API method is by using literal expressions. This is fine if you want to know the TQI value for a fixed path in your archive (e.g. HIE://MYPROJECT/trunk), but if you want to retrieve data for paths that you cannot specify up-front (or do not want to), you can use the following expressions and helper functions:

Expression Description
path literal

A path literal is a combination of a hierarchy specifier (HIE or ORG), followed by '://', and then followed by a '/'-separated list of names. The first name is always the project name, the second name is the branch name. The remaining names denote folders. The last name can denote a file. For example, HIE://MYPROJECT/trunk/path/to/file.cpp denotes file named "file.cpp" in folder "path/to" in branch "trunk", project "MYPROJECT". HIE://MYPROJECT/trunk denotes the root folder in the branch. ORG://MYPROJECT/trunk denotes the root folder of the same branch in the ORG hierarchy. The ORG hierarchy is only available if you have configured this view for your project.

Escaping: Because the characters ,, (, and ) have a special purpose in expressions you need to escape them using backslash (\) if they occur in the filename.
a,b,... Returns the union of given paths. Example: HIE://MYPROJECT/trunk,HIE://MYPROJECT/release. The elements can be also be expressions. Example: Children(HIE://MYPROJECT/trunk/folder1),Children(HIE://MYPROJECT/trunk/folder2).
Children(paths) Returns the direct children of one or more input paths. For example, use Children(HIE://MYPROJECT) to obtain the list of branches for MYPROJECT. Because Children accepts a list of paths, you can nest calls. For example, Children(Children(HIE://MYPROJECT)) returns a list of all top-level folders for all branches in MYPROJECT.
Descendants(path) Returns all descendant files and folders that have path as ancestor.
Files(paths) Returns the subset of paths that denote files, leaving out folders, branches, and projects. For example, use Files(Descendants(HIE://MYPROJECT/trunk)) to return all files for branch "trunk".
Folders(paths) Returns the subset of paths that denote folders, leaving out files.

Metric Expressions

In its simplest form a metric expression refers to a single metric, such as loc or tqiFanOut. However, more complex metrics can be obtained using metric generators. A metric generator is a function (named "G") applied to a single metric and one or more modifiers and produces one or more derived metrics that can be used for any API parameter where a list of metrics is expected. For example, in the expression G(loc,Language()) the Language modifier is applied to the loc metric to obtain the Lines of Code per language:


The available modifiers are:

Modifier Description

Refines a metric to specific programming language. Programming language needs to be specified using one of the built-in programming language identifiers. For example, to get the lines of code for Java:


Refines a violation metric to a specific coding rule name, category, or level. For example, to get the coding standard violations for level 1 use:


Provide a comma-separated list of rule property values to create multiple metrics. For example, to get the coding standard violations for categories Basic and Design use:


Omit the parameter to split by all available property values. For example, to create a metric for each available rule:


Modifies a violation metric to divide its result by lines of code × 1000. For example, to get the number of coding standard violations per thousand lines of code use:


Modifies tqi metrics to take targets into account that have been entered in the TQI calculator. For example, the metric expressed as G(tqi,Scenario(default)) produces TQI scores that are affected by all targets entered in the TQI calculator. The modifier expects a single parameter: the name of the scenario whose targets should be considered. Currently only one scenario is supported: the scenario named "default".

For example, to get the target TQI score:


ToImage API

Use the ToImage endpoint to download the TQI Label as an image (png format) programmatically, or to embed the TQI Label in your own webpage:


To obtain a URL that you can use in your own application, go to the Dashboard and select the project and/or filters that you want to generate a TQI Label for. Then, right click the Download Image button beneath the TQI Label and choose "copy link address". You can use this URL in your application to download the TQI Label with the most actual data.

The parameters of the ToImage API are:

Parameter Value Required Description
url base64 encoded URL (relative) yes The easiest way to determine this parameter is to follow the steps above. You can also generate it programmatically by base64 encoding the following (relative) URL: TqiLabel.html#axes=Project(MYPROJECT)&print=true, where MYPROJECT should be replaced by the project name that you want to generate the label for.
disposition attachment or inline No (default=inline) The disposition type used by the HTTP response. Use the value attachment to indicate that the browser should prompt the user to save the response locally. Use the value inline to have the browser process the response normally (as per its media type), which can be used to embed the image in your dashboard (e.g. using an IFRAME).
filename name of file, ending with .png Only when disposition is set to attachment The default filename to be used by the browser when disposition is attachment. The filename should end in .png.
zoom The zoom factor No (default=1) Use this to generate a higher-resolution image (up to 4 times).

If you have configured authentication, you have to provide the required credentials using Basic HTTP Authentication. For instance, if you are using the GNU tool wget, you can provide a username and password as follows:

wget "ToImage?format=png&url=BASE64URL" --user USERNAME --password PASSWORD -O TQILabel.png

Annotations API

Use the Annotations API to retrieve a list of all annotations for violations of a given type (Coding Standard Violations, Compiler Warnings, or Abstract Interpretation Violations) and for a certain project. For instance, the following URL returns a JSON object containing all Coding Standard violations for project :


The input parameters of the Annotations API are:

Parameter Value Required Description
metric One of Annotations(CS), Annotations(CW), Annotations(AI) yes Specifies whether to retrieve annotations for Coding Standards (Annotations(CS)), Compiler Warnings (Annotations(CW)), or Abstract Interpretation (Annotations(AI)).
filters A comma-separated list of filters that you want to apply Project(…) filter is mandatory

Specifies the filters that should be applied. All filters are optional except for the Project filter. The following filters are supported:

  • Project(…): only return annotations for this project.
  • Language(…): only return annotations for this language. The language should be specified using one of the built-in language identifiers.
  • Level(…),Category(…),Rule(…): only return annotations for given level, category, or rule.
  • Suppressions(…): whether suppressed violations should be included. Suppressed violations are omitted by default. Specify Suppressions(yes) to only get suppressed violations. Specify Suppressions(either) to get both suppressed and unsuppressed violations.
  • View(…): whether to retrieve annotations for the Hierarchical (View(HIE)), Organizational (View(ORG)), or Rational Rose (View(RR)) view (where configured). If omitted, the Hierarchical view is used.
  • Sub(…): only return annotations for the given subsystem. You can specify multiple Sub filters to specify a nested subsystem. For example, to get all annotations for the component comp in module mod in the organizational view of project X, you would use: Project(X),View(ORG),Sub(mod),Sub(comp).

The order in which you specify the filters is not important, except for the Sub filters.

The JSON output fields are:

Field Description

A JSON object containing meta-data about the response. Currently, it only contains a title field:

title string Comprehensive title describing which annotations are in the response. Do not rely on the specific contents of this string, as it might change in the future!

An array of Annotation objects that pass the given filters, in no particular order. Each object contains the following fields:

fullPath string The full path name, e.g. HIE:////path/to/file.cpp
line number The line number on which the violation occurred
level number The violation's level
category string The violation's category name
rule string The violation's rule name
msg string The message of the annotation
supp boolean Whether the violation is suppressed by the violation suppression mechanism or not. By default, only unsuppressed violations will be shown unless you specify a Suppression(…) filter (see above).
count number The number of violations that this annotation represents. This is usually 1. However, it sometimes happens that a code checker produces multiple violations with the exact same line number, rule, and message. This might happen for instance when there is a violation on a line produced by a C++ macro expansion.
Warning: Depending on the number of annotations, the query can become slow and the response might become large. Consider adding filters such as a Language filter to prevent this.


The Web API respects any authentication that you might have configured in your SERVER.txt. If you try to acquire data for a project without providing proper credentials, the server responds with a HTTP status code 401: Unauthorized. Use HTTP basic access authentication to access projects that require authentication. Most HTTP client libraries support basic authentication. Please consult the documentation of the library that you use. The Web API uses HTTP realm "TICS".

How To

How to get a list of all projects or a list of all branches for a project?

To get a list of all projects, use the Measure API with metric none on the root node HIE://, as follows:


The response is formatted like any other Measure API call. The data field of the response is not of interest, as we specified the none metric. However, the nodes field contains an array of path objects, one for each project that you have configured:

  "data": [{
      "formattedValue": null,
      "letter": null,
      "value": null,
      "total": 0,
      "success": 0
  }, ...],
  "dates": [
  "metrics": [{
      "expression": "none",
      "fullName": "-"
  "nodes": [{
      "name": "MYPROJECT1",
      "fullPath": "HIE://MYPROJECT1"
      "name": "MYPROJECT2",
      "fullPath": "HIE://MYPROJECT2"

The fullPath field can be used as input parameter for any follow-up Measure API calls. For example, to get a list of branches for project :


Appendix: Metrics

A list of commonly used metric expressions is found below. Expressions for metrics that are not listed here can be found by opening a trend diagram for the desired metric. You will find the expression in the browser window's URL bar.

Expression Description
loc Lines of code
eloc Effective lines of Code
gloc Lines of code including generate code
cycloxAverage Average cyclomatic complexity
cycloxMax Maximum cyclomatic complexity
cycloxTotal Total cyclomatic complexity
fanOut Average fan out
nrOfFunctions Number of functions
deadCode Dead Code (percentage)
duplicatedCode Code Duplication (percentage)
tqi TIOBE Quality Indicator
tqiTestCoverage TQI Code Coverage
tqiAbstrInt TQI Abstract Interpretation
tqiComplexity TQI Cyclomatic Complexity
tqiCompWarn TQI Compiler Warnings
tqiCodingStd TQI Coding Standards
tqiDupCode TQI Code Duplication
tqiFanOut TQI Fan Out
tqiDeadCode TQI Dead Code
linesAdded, linesDeleted, linesChanged Sum of lines added, deleted, or changed in this run
changerate Change rate (total of lines added, deleted, and changed)
accuChangerate Accumulative change rate over all runs
where scope is one of unit, system, integration, or total
and type is one of Branches, Statements, Functions, or Decisions
Unit, System, Integration, or Total Code coverage for Branches, Statements, Functions, or Decisions (16 possible combinations)
Violations(+type+) where type is one of CS,CW,AI

Total number of coding standard violations, compiler warnings, or abstract interpretation violations

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD, violations::type=COMPILERWARNING, violations::type=ABSTRACTINTERPRETATION


Number of coding standard violations for level 1

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD\,level=1


Number of coding standard violations for category "Basic"

Deprecated pre-7.4 syntax: violations::type=CODINGSTANDARD\,category=Basic


Number of coding standard violations per 1000 lines of code

Deprecated pre-7.4 syntax: vkloc::type=CODINGSTANDARD


Compliance with respect to coding standard violations (percentage)

Deprecated pre-7.4 syntax: confidence::type=CODINGSTANDARD

Appendix: JSONP

When you try to access the WebAPI using JavaScript that is running in your browser, you will run into the browser's same-origin policy. This security policy prevents your script from accessing data on the TICS Viewer, because it is located on a different origin (the combination of hostname, port number, and URI scheme). To overcome this issue, the WebAPI supports JSONP. Another way to overcome the same-origin policy is Cross-origin resource sharing (CORS), but this is not yet supported by the TICS Viewer.

To use JSONP, you have to change the WebAPI URL to include a query parameter named callback, whose value is the name of a JavaScript function that is defined in your script. Instead of the normal JSON payload, the response will be a JavaScript function call to the specified function using the JSON payload as the function's argument. Libraries such as jQuery and Angular support the JSONP convention. Please refer to their respective documentation pages.

Appendix: Languages

When referring to a programming language in the API or in the TICS configuration, you should refer to the languages identifier. Below is a list of supported programming languages and their identifiers.

Programming Language Identifier