Mapp Intelligence JSON/RPC API

Mapp Intelligence JSON/RPC API allows you to recall data from Mapp automatically.

Please note that from the end of June 2024, HTTP can no longer be used.

The connection occurs via HTTPS protocols.

URL: https://report2.webtrekk.de/cgi-bin/wt/JSONRPC.cgi

Methods

The following methods are available by the JSON/RPC API:

Errors

Errors are received in the parameter “error” in the result.

Example:
{
	"version": "1.1",
	"error": {
		"name": "JSONRPCError",
		"message": "Authorization failed",
		"code": 501
	}
}

Connection Test

To test the connection, you use the method „getConnectionTest. " This method works without login data or other parameters. The string „Connection successful“ obtains the test result.

Request

Response

Example:
{

	"version": "1.1",

	"result": "Connection successful“
}

Login

By using the method „login, " you retrieve a token to use in the following requests. If you use it at least once per hour, the token is valid until you log out. If you don't, it becomes invalid.

Request

Example:

{

	"params": {

		"login": "login",

		"pass": "pass",

		"customerId": "11111111111",

		"language": "en"

	},

	"version": "1.1",
	"method": "login"
}

Response

The response to the message is the token.

Example:

{

	"version": "1.1",

	"result": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270"

}

Logout

By using the method „logout“ you delete a token.

Request

Example:

{

	"params": {

		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270"

	},

	"version": "1.1",
	"method": "logout"
}

Response

The result is “1” if the logout was successful, otherwise “0”.

Example:

{

"version": "1.1",

"result": "1"

}

Account List

By using the method „getAccount“ you retrieve information about all available Accounts for a login.

Request

Example:

{

	"params": {

		"login": "login",

		"pass": "pass"

	},

	"version": "1.1",

	"method": "getAccountList"
}

Response

The result is an array of account information.

Example:

{

	"version": "1.1",

	"result": [

		{

		"customerId": "11111111111",

		"title": "Account 1"

		},

		{

		"customerId": "11111111112",

		"title": "Account 2"

		}

	]

}

Analysis Objects and Metrics List

By using the method „getAnalysisObjectsAndMetricsList“ you retrieve information about all available analysis objects and metrics in an account.

Request

Example:

{

	"params": {

		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270"

	},

	"version": "1.1",

	"method": "getAnalysisObjectsAndMetricsList"
}

Response

The results are three arrays of Analysis Objects, Metrics, and Customer Scores.

Example:

{

	"version": "1.1",

	"result": {

		"analysisObjects": [

			"Plugins",

			"Provider",

			"Region",

			"Pages",

		]

		"metrics": [

			"Page Impressions",

			"Visitors",

			"Visits",

		],


		"customMetrics": [
			"Engagement",
			"Page Impressions on index pages",
			"Visits Google",
		],
	}
}

Custom Reports List

By using the method „getCustomReportsList“ you retrieve information about all available reports in an account.

Request

Example:
{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270"
	},
	"version": "1.1",
	"method": " getCustomReportsList"
}

Response

The result is an array of all reports with their report groups.

Example:

{

	"version": "1.1",

	"result": [

		{

			"reportGroup": "Dashboards",

			"title": "E-Commerce Dashboard"

		},

		{

			"reportGroup": "",

			"title": "Clicks
		}
	]
}

Dynamic Time Interval List

By using the method „getDynamicTimeIntervalList“ you retrieve information about all available dynamic time intervals in an account.

Request

Example:

{

	"params": {

		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270"

	},

	"version": "1.1",

	"method": "getDynamicTimeIntervalList"
}

Response

The result is an array of all dynamic time intervals and the codes to use in getAnalysisData function.

Example:

{

	"version": "1.1",

	"result": [

		{

			"name": "Today",

			"code": "today"

		},

		{

			"name": "Yesterday",

			"code": "yesterday"

		},

	]

}

Analysis Requests

By using the method „getAnalysisData“ you retrieve data of various analyses.

Request

analysisConfig

analysisObject

metric

filter

filterRule

Example:
{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",
		"analysisConfig": {
			"hideFooters": 1,
			"analysisFilter": {
				"filterRules": [{
					"objectTitle": "Pages",
					"comparator": "=",
					"filter": "*manieren*",
					"scope": "visit"
				},
				{
					"link": "and",
					"objectTitle": "Browser",
					"comparator": "!=",
					"filter": "*Chrome*"
				}]
			},
			"metrics": [{
				"sortOrder": "desc",
				"title": "Page Impressions"
			},
			{
				"title": "Visits",
				"metricFilter": {
					"filterRules": [{
						"objectTitle": "Pages",
						"comparator": "=",
						"filter": "*index*"
					}]
				}
			}],
			"rowLimit": 10000,
			"analysisObjects": [{
				"title": "Pages"
			},
			{
				"sortOrder": "asc",
				"title": "Days"
			}]
		}
	},
	"version": "1.1",
	"method": "getAnalysisData"
}

Response

Please note: If the analysis object is a time object the “total” values in responses are unique values (the analysis type “analysis” switches to “pivot” in the JSON response).

Example for analysisType „analysis“:
{
	"version": "1.1",
		"result": {
			"analysisWarnings": [],
			"dailyUnique": 0,
			"totalRowCount": 1504,
			"analysisTabHead": [
				{
					"dataType": "string",
					"title": "Seiten",
					"contentType": "main"
				},
				{
					"dataType": "number",
					"title": "Page Impressions",
					"contentType": "normal"
				},
				{
					"dataType": "number",
					"title": "% Page Impressions",
					"contentType": "percent"
				}
			],
			"timeStop": "2011-01-20 23:59:59",
			"calculationTime": "2011-01-20 12:12:22",
			"analysisTabFoot": [
				[
					"",
					"Gesamt",
					"211165",
					"100.00"
				]
			],
				"analysisData": [
					[
						"1",
						"manieren_per_mausklick",
						"17213",
						"8.15"
					],
					[
						"2",
						"index",
						"10000",
						"4.74"
					],
				],
			"timeStart": "2010-12-21 00:00:00",
			"analysisTitle": "Seiten",
			"chartType": "bars",
			"analysisType": "analysis"
		}
}

Example for analysisType „scorecard“:
There is an additional hashtable “scorecardData” which has data for the visualization of the scorecard
and has the parameters “analysisTabHead” and “analysisData” and also the scorecardValue, which is
the value presented next to the visualization.
{
	"version": "1.1",
	"result": {
	"analysisWarnings": [
	],
	"scorecardData": {
		"analysisTabHead": [
			{
				"dataType": "number",
				"title": "Date",
				"contentType": "normal"
			},
			{
				"dataType": "number",
				"title": "Score",
				"contentType": "normal"
			}
		],
		"scorecardValue": "8",
		"analysisData": [
			[
				"29.12.2010",
				"5"
			],
			[
				"30.12.2010",
				"5"
			],
			[
				"31.12.2010",
				"5"
			],
			[
				"01.01.2011",
				"5"
			],
			[
				"02.01.2011",
				"5"
			],
			[
				"03.01.2011",
				"4"
			],
			[
				"04.01.2011",
				"5"
			],
			[
				"05.01.2011",
				"5"
			],
			[
				"06.01.2011",
				"5"
			],
			[
				"07.01.2011",
				"4"
			],
			[
				"08.01.2011",
				"4"
			],
			[
				"09.01.2011",
				"3"
			],
			[
				"10.01.2011",
				"4"
			],
			[
				"11.01.2011",
				"5"
			],
			[
				"12.01.2011",
				"5"
			],
			[
				"13.01.2011",
				"5"
			],
			[
				"14.01.2011",
				"5"
			],
			[
				"15.01.2011",
				"5"
			],
			[
				"16.01.2011",
				"5"
			],
			[
				"17.01.2011",
				"5"
			],
			[
				"18.01.2011",
				"6"
			],
			[
				"19.01.2011",
				"7"
			],
			[
				"20.01.2011",
				"7"
			],
			[
				"21.01.2011",
				"7"
			],
			[
				"22.01.2011",
				"7"
			],
			[
				"23.01.2011",
				"7"
			],
			[
				"24.01.2011",
				"8"
			],
			[
				"25.01.2011",
				"8"
			],
			[
				"26.01.2011",
				"8"
			],
			[
				"27.01.2011",
				"9"
			],
			[
				"28.01.2011",
				"8"
			]
		]
	},
	"analysisType": "scorecard",
	"dailyUnique": 0,
	"totalRowCount": 0,
	"analysisTabHead": [
		{
			"dataType": "string",
			"title": "Key figure",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Today and last 30 days",
			"contentType": "normal"
		},
		{
		"dataType": "number",
		"title": "Today and last 30 days (%)",
		"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Last 7 days",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Last 7 days (%)",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Last 14 days",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Last 14 days (%)",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Last 90 days",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Score",
			"contentType": "normal"
		}
	],
	"timeStop": "2011-01-28 23:59:59",
	"calculationTime": "2011-02-24 14:21:07",
	"chartType": "lines",
	"analysisTabFoot": [
	],
	"analysisData": [
		[
			"Page Impressions",
			"7562",
			"-2.2",
			"7733",
			"-0.9",
			"7805",
			"33.8",
			"5835",
			"10"
		],
		[
			"Visitors",
			"1503",
			"-3.3",
			"1554",
			"-3.7",
			"1614",
			"29.4",
			"1247",
			"7"
		]
	],
	"timeStart": "2010-12-29 00:00:00",
	"analysisTitle": "Scorecard"
	}
}

Example for analysisType „status“:
There is an additional array “kpiData” which has data for the visualization of the status kpi
(=speedometer). This is a simple table of two or three rows.
{
	"version": "1.1",
	"result": {
		"analysisWarnings": [
		],
		"kpiData": [
			[
				"Durchschnitt",
				"7733"
			],
			[
				"Gesamt",
				"54134"
			]
		],
		"analysisType": "status",
		"dailyUnique": 0,
		"totalRowCount": 7,
		"analysisTabHead": [
			{
				"dataType": "string",
				"title": "Tage",
				"contentType": "main"
			},
			{
				"dataType": "number",
				"title": "Page Impressions",
				"contentType": "normal"
			}
		],
		"timeStop": "2011-01-27 23:59:59",
		"calculationTime": "2011-02-24 14:30:11",
		"chartType": "lines",
		"analysisTabFoot": [
			[
				"Gesamt",
				"54134"
			]
		],
		"analysisData": [
			[
				"21.01.2011",
				"8228"
			],
			[
				"22.01.2011",
				"4918"
			],
			[
				"23.01.2011",
				"7975"
			],
			[
				"24.01.2011",
				"9261"
			],
			[
				"25.01.2011",
				"8294"
			],
			[
				"26.01.2011",
				"7403"
			],
			[
				"27.01.2011",
				"8055"
			]
		],
		"timeStart": "2011-01-21 00:00:00",
		"analysisTitle": "KPI"
	}
}

Example for analysisType „pivot“:
This is the same as the analysis for analysisType “analysis”, except there can be more than one
elements in the analysisTabHead parameter with contentType “main”
{
	"version": "1.1",
	"result": {
		"analysisWarnings": [
		],
	"analysisType": "pivot",
	"dailyUnique": 0,
	"totalRowCount": 10078,
	"analysisTabHead": [
		{
			"dataType": "string",
			"title": "Browser",
			"contentType": "main"
		},
		{
			"dataType": "string",
			"title": "Pages",
			"contentType": "main"
		},
		{
			"dataType": "number",
			"title": "Page Impressions",
			"contentType": "normal"
		},
		{
			"dataType": "number",
			"title": "Visitors",
			"contentType": "normal"
		}
	],
		"timeStop": "2011-01-28 23:59:59",
		"calculationTime": "2011-02-24 14:35:44",
		"chartType": "bars",
		"analysisTabFoot": [
		],
		"analysisData": [
			[
				"Firefox 3.6",
				"manieren_per_mausklick",
				"6551",
				"4616"
			],
			[
				"Firefox 3.6",
				"dresscode_einmaleins",
				"2188",
				"1648"
			],
			[
				"Firefox 3.6",
				"-",
				"83160",
				"15008"
			],
			[
				"Internet Explorer 8.x",
				"manieren_per_mausklick",
				"4530",
				"2872"
			],
			[
				"Internet Explorer 8.x",
				"-",
				"0",
				"1503"
			],
			[
				"Internet Explorer 8.x",
				"-",
				"59680",
				"11502"
			],
			[
				"-",
				"-",
				"226857",
				"42673"
			]
		],
		"timeStart": "2010-12-29 00:00:00",
		"analysisTitle": "Pivot"
	}
}

Request of Reports

By using the method „getReportData“ you can retrieve data from reports.

Request

Example:
{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",
		"report_name": "Overview Report"
	},
	"version": "1.1",
	"method": "getReportData"
}

Response

Example:
{
	"version": "1.1",
	"result": {
		"author": "John Doe",
		"title": "Overview Report",
		"description": "",
		"analyses": […]
	}
}

Data Export

By using the method „exportData“ you can export category/parameter data. The Limit for exportable rows is 10.000 by default. If more rows are to be exported then it is possible to split the data using the startRow and endRow parameters to export, for example, rows 1 to 10.000, then rows 10.001 to 20.000, and so on.

Request

Example:
{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",
		"startRow": 1,
		"endRow": 1000,
		"type": "content_categories"
	},
	"version": "1.1",
	"method": "exportData"
}

Response

Example:
{
	"version": "1.1",
	"result": [
		["Pages", "Category (Text) – Main category", "Category (Figure) – ownC. "],
		["index", "archive", "1"],
		["home", "archive", "2"]
	]
}

Data Import

By using the method „importData“ you can import category/parameter data. The Limit for importable rows is 10.000 by default.

Request

Example for content group import

{

	"params": {

		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",

		"uploadType": "content_categories",

		"uploadData": [

			["Pages", "Category (Text) – Main category", "Category (Figure) – ownC. "],

			["index", "archive", "1"],

			["home", "archive", "2"]

		]

	},

	"version": "1.1",

	"method": "importData"

}

Example for changing a campaign

It will rename the campaign <Mediacode1> to <newCampaignName1>, <Mediacode2> to
<newCampaignName2> and so on.

{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",
		"uploadType": "campaigns",
		"uploadData": [
			[
				"Action (delete, suggest)",
				"Advertising Media Title*",
				"DataSourceType (page, mediacode, action, seo, referrer)",
				"DataSourceValue*"
			],
			[
				"",
				<newCampaignName1>,
				"mediacode",
				<Mediacode1>
			],
			[
				"",
				<newCampaignName2>,
				"mediacode",
				<Mediacode2>
			],
			...
			[
				"",
				<newCampaignNameN>,
				"mediacode",
				<MediacodeN>
			]
		]
	},
	"version": "1.1",
	"method": "importData"
}

Example for deleting a campaign

It will delete the campaigns with <Mediacode1>, <Mediacode2>, and so on.
It is also possible to merge different actions in one upload for changing and deleting campaigns.

{
	"params": {
		"token": "98991ec3459031c4bd9ddfeb4e142045_52b6b54cbb4e9654d1ff032521a86270",
		"uploadType": "campaigns",
		"uploadData": [
			[
				"Action (delete, suggest)",
				"Advertising Media Title*",
				"DataSourceType (page, mediacode, action, seo, referrer)",
				"DataSourceValue*"
			],
			[
				"delete",
				<CampaignName1>,
				"mediacode",
				<Mediacode1>
			],
			[
				“delete",
				<CampaignName2>,
				"mediacode",
				<Mediacode2>
			],
			...
			[
				"delete",
				<CampaignNameN>,
				"mediacode",
				<MediacodeN>
			]
		]
	},
	"version": "1.1",
	"method": "importData"
}

Example for User Category Import via Custom Visitor Id

{
	"params": {
		"token": "c7a0768a865b9a20a6ba2278e6ebf686_6f9d875ca7abdf76969f07a2fefcdaba",
		"uploadType": "customer_categories",
		"uploadData": [
			[
				"Customer",
				"URM – Category Name",
				"URM - Gender"
			],
			[
				"508371",
				"Caras 1116",
				"Woman"
			]
		]
	},
	"version": "1.1",
	"method": "importData"
}

Example for User Category Import via End Device Visitor Id

User Categories are related to one Custom Visitor ID. If you’re Account is configured to run cross-device, several End Device Visitor Ids can belong to one Custom Visitor ID. Please be aware, that if you upload different values for a category to different devices of one customer, only one value will be taken. We recommend using the Upload via Custom Visitor ID instead.

{
	"params": {
		"token": "c7a0768a865b9a20a6ba2278e6ebf686_b431121901c3e97ed8da17fc331da9c4",
		"uploadType": "customer_categories_deid",
		"uploadData": [
			[
				"deid",
				"URM – Category Name",
				"URM - Gender"
			],
			[
				"2148028690700883469",
				"Caras 1116",
				"Woman"
			]
		]
	},
	"version": "1.1",
	"method": "importData"
}

Example for e-commerce parameter upload

Note that single and multi-value parameters need to be uploaded separately

• For single-value parameters the order ID is sufficient to link the imported parameter value

• For multi-value parameters the import requires the order ID and products of the order, so that every product can get a value assigned

  • Object for products is  “productname”  in the API, not products as in the UI

Example import with multi-value parameter named "Parameter (Text) - JSON API Text 2 Several Values":

{
    "params": {
        "uploadType": "ecommerce_parameters",
        "token": "f8f2a47c878d7de31c9d79d38d36d7d9_6291e6d0653c00a683bccff995b5469a",
        "uploadData": [
            [
                "Order ID",
                "Productname",
                "Parameter (Text) - JSON API Text 2 Several Values"
            ],
            [
                "1976794766",
                "995eo1e900",
                "prod one test"
            ],
            [
                "1976794766",
                "035ek2w007",
                "prod two test"
            ]
        ]
    },
"version": "1.1",
	"method": "importData"
}

Response

Example:
{
	"version": "1.1",
	"result": []
}

TV data deletion

By using the method „deleteTvData“ you initiate the deletion of TV data.

Request

Example:

{

	"params": {

		"login": "login",

		"pass": "pass",

		"customerId": "11111111111",

		"time_start": "2013-12-01 00:00:00",

		"time_stop": "2013-12-31 23:59:59"

	},

	"version": "1.1",

	"method": "deleteTvData"
}

Response

Example:
{
	"version": "1.1",
	"result": ["Deleting Tv Data initiated"]
}

Request Limitations

To prevent blocking the JSON API and the server by a high frequency of API requests of one customer the number of requests per time period is limited. If one single Q3 user sends requests to the JSON API with a frequency higher than the defined limits, the JSON API will refuse subsequent requests for the defined period. The following values define the limitations.

Short-term limit

The short-term limit applies if the customer sends a lot of requests in a relatively short period, e.g., 1 request per second. In the default configuration, the limitation applies after 10 seconds when there are more than 1 requests per 2 seconds. After the limit is reached the following request will be accepted 1 per 10 seconds until the frequency returns to the allowed level.

Long-term limit

The long-term limit applies if the customer sends a lot of requests in a relatively long period of time, e. g. 1 request every 4 seconds. In the default configuration, the limitation applies after 10 minutes (600 seconds) when there are more than 120 requests within this period. After the limit is reached the following request will be accepted 1 per 10 minutes until the frequency returns to the allowed level. The long-term limit will also be applied to the requests that are limited by the short-term limit and still coming with the same frequency within

the long-term period.  In case a limit is reached, the API will respond with the following message and header:

{
	"version":"1.1",
	"error": {
			"name": "JSONRPCError",
			"message": "To many requests ([JSON_REQUESTS_ALLOWED_PER_PERIOD |
			JSON_REQUESTS_ALLOWED_PER_PERIOD_SEC]) within
			[JSON_REQUESTS_PERIOD | JSON_REQUESTS_PERIOD_SEC] seconds."
	},
	"code" : 501
}
HTTP-Header:
Status: 200 OK
Content-Type: application/x-www-form-urlencoded

Example:

{
	"version":"1.1",
	"error": {
		"name": "JSONRPCError",
		"message": "To many requests (120) within 600 seconds."
	},
	"code" : 501
}
HTTP-Header:
Status: 200 OK
Content-Type: application/x-www-form-urlencoded

Please note that the described limitations can not be changed individually per account. We reserve the right to change the limitation values if there is still a risk of blocking the API with the current values.