In this document, commands of version 1.0 of Gem API are presented. The main command is the /v1/stats command, which allows retrieving data from the Gemius Audience study. Other commands:
are used for retrieving metadata, which are used as parameters to the /v1/stats command.Data can be retrieved in json or csv with TAB as a columns separator format.
Opens REST Gem API session.
Json dictionary with fields:
Csv file with one column and sinlge row for session key.
{
"api_version": 1,
"data": {
"session": "1234567890xxxxxxxxxxxxxxxxxxxxxx"
}
}
session
269d9108eff79edc725d7930658d785f
List data periods available for user.
Json dictionary with fields:
Csv file with one row for each available period. Output has columns: begin, country, end and period type, which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": {
"pl": {
"daily": [
{
"begin": "2017-02-15",
"end": "2017-02-16"
},
],
"monthly": [
{
"begin": "2016-08-01",
"end": "2016-09-01"
},
]
}
}
}
begin country end period type
2016-01-29 pl 2016-01-30 other
2017-05-11 pl 2017-05-12 daily
2016-06-06 rs 2016-06-13 weekly
2016-06-01 rs 2016-07-01 monthly
List all posible geolocations in selected period.
Json dictionary with fields:
Csv file with one row for each available geolocation. Output has columns: id, name, which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"id": 1,
"name": "Domestic"
}
],
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
id name
1 Domestic
List all posible platforms in selected period.
Json dictionary with fields:
Csv file with one row for each available platform. Output has columns: id, is_static, name, parent_id (id of parent platform) which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"children": [
{
"children": [
{
"id": 104,
"is_static": false,
"name": "pc-home"
},
{
"id": 105,
"is_static": false,
"name": "pc-work"
}
],
"id": 101,
"is_static": false,
"name": "pc"
},
{
"children": [
{
"id": 102,
"is_static": false,
"name": "mobile-phones"
},
{
"id": 103,
"is_static": false,
"name": "mobile-tablets"
}
],
"id": 100,
"is_static": false,
"name": "mobile"
}
],
"id": 99,
"is_static": false,
"name": "total"
}
],
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
id is_static name parent_id
99 False total
101 False pc 99
104 False pc-home 101
105 False pc-work 101
100 False mobile 99
102 False mobile-phones 100
103 False mobile-tablets 100
List all posible metrics in selected period.
Json dictionary with fields:
Csv file with one row for each available metric. Output has columns: id, name, type, which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"id": 7,
"name": "Real users",
"type": "n"
},
{
"id": 8,
"name": "Page views",
"type": "n"
},
{
"id": 9,
"name": "Page views per real user",
"type": "n"
},
{
"id": 11,
"name": "Time [s]",
"type": "n"
},
{
"id": 25,
"name": "Visits",
"type": "n"
},
{
"id": 100,
"name": "Affinity Index-Internet (relative)",
"type": "n"
},
{
"id": 110,
"name": "Reach-Internet",
"type": "n"
}
],
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
id name type
7 Real users n
8 Page views n
11 Time [s] n
25 Visits n
29 Min audience duplication n
30 Min audience duplication (%) n
31 Max audience duplication n
32 Max audience duplication (%) n
100 Affinity Index-Internet (relative) n
110 Reach-Internet n
List all posible trees in selected period.
Json dictionary with fields:
Csv file with one row for each available tree. Output has columns: id, name which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"id": "59857",
"name": "Internet"
},
{
"id": "497408.1.497408.1",
"name": "Drzewko funkcjonalne ogólne"
},
{
"id": "497406.1.497406.1",
"name": "Drzewko funkcjonalne szczegółowe"
},
{
"id": "343670.1.343670.1",
"name": "Drzewko sieci"
},
{
"id": "497407.1.497407.1",
"name": "Drzewko tematyczne ogólne"
},
{
"id": "497405.1.497405.1",
"name": "Drzewko tematyczne szczegółowe"
}
],
"source": {
"begin": "2017-07-13",
"country": "pl",
"end": "2017-07-14"
}
}
id name
59857 Internet
497408.1.497408.1 Drzewko funkcjonalne ogólne
497406.1.497406.1 Drzewko funkcjonalne szczegółowe
343670.1.343670.1 Drzewko sieci
497407.1.497407.1 Drzewko tematyczne ogólne
497405.1.497405.1 Drzewko tematyczne szczegółowe
List all posible nodes in selected period.
Json dictionary with fields:
Csv file with one row for each available node. Output has columns: id, name, parent_id (id of parent node), type, audited, which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"children": [
{
"children": [
{
"children": [
{
"id": "448744",
"name": "serwis",
"type": "s",
"audited": false
}
],
"id": "59639",
"name": "domena",
"type": "w",
"audited": false
}
],
"id": "59633",
"name": "Grupa",
"type": "u",
"audited": false
}
],
"id": "59857",
"name": "Internet",
"type": "k",
"audited": false
}
],
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
id name parent_id type audited
59857 Internet k False
59633 Grupa 59857 u False
59639 domena 59633 w False
448744 serwis 59639 s False
List demography traits in selected period.
Json dictionary with fields:
For continuous traits, list may contain predefinied segments, described by json object with fields:
For discreete traits, list contain answers, described by json object with fields:
Csv file with three sections. The first one contains data of demography traits. The second contains data of discreete traits' values. The third part contains default segments for continuous traits.
The first part has one row for each available trait. It has columns: continuous, id, name, which meanings correspond to the json output fields in data part.
The second part has one row for each available discreete trait value. It has columns: id, name, trait_id (id of discreete trait), which meanings correspond to the json output fields in data part.
The third part has one row for each available continuous trait predefined segment. It has columns: max, min, trait_id (id of continuous trait), which meanings correspond to the json output fields in data part.
{
"api_version": 1,
"data": [
{
"answers": [
{
"id": 1,
"name": "kobieta"
},
{
"id": 2,
"name": "mężczyzna"
}
],
"continuous": false,
"id": 0,
"name": "Płeć"
},
{
"answers": [
{
"max": "14",
"min": "7"
},
{
"max": "24",
"min": "15"
},
{
"max": "34",
"min": "25"
},
{
"max": "44",
"min": "35"
},
{
"max": "54",
"min": "45"
},
{
"max": null,
"min": "55"
}
],
"continuous": true,
"id": 1,
"name": "Wiek"
},
],
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
continuous id name
False 0 Płeć
True 1 Wiek
id name trait_id
1 kobieta 0
2 mężczyzna 0
max min trait_id
14 7 1
24 15 1
34 25 1
44 35 1
54 45 1
55 1
Shows statistics for selected parameters.
Json dictionary with fields:
Each statistics object contains fields:
The filtered object contains fields:
Csv file with one row for each data point. Output has columns: geo_id, node_id, platform_id, target_group, which meanings correspond to the json output fields in data/stats part. Moreover, output has columns corresponding to selected metrics. Columns are in an alphabetical order.
men_25-30:0=2and1=25;30
0=1and1=25;30and2=14or0=1and1=25;30and2=18
...&target=definition_of_gt_1&target=definition_of_gt_2...
{
"api_version": 1,
"data": {
"filtered": {
"geos": [],
"metrics": [],
"nodes": [],
"platforms": [],
"targets": []
},
"stats": [
{
"Page views": "3529980",
"Real users": "264953",
"geo_id": 1,
"node_id": "58751",
"platform_id": "101",
"target_group": "men_25-30"
},
{
"Page views": "-1",
"Real users": "-1",
"geo_id": 1,
"node_id": "58752",
"platform_id": "101",
"target_group": "men_25-30"
}
]
},
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
Page views Real users geo_id node_id platform_id target_group
3529980 264953 1 58751 101 men_25-30
-1 -1 1 58752 101 men_25-30
Lets assume, that queried period has not available foreign statistics. By using strict parameter, one can obtain two results.
strict=False
{
"api_version": 1,
"data": {
"filtered": {
"geos": [
2
],
"metrics": [],
"nodes": [],
"platforms": [],
"targets": []
},
"stats": [
{
"Page views": "3529980",
"Real users": "264953",
"geo_id": 1,
"node_id": "58751",
"platform_id": "101",
"target_group": "men_25-30"
},
{
"Page views": "-1",
"Real users": "-1",
"geo_id": 1,
"node_id": "58752",
"platform_id": "101",
"target_group": "men_25-30"
}
]
},
"source": {
"begin": "2017-05-25",
"country": "pl",
"end": "2017-05-26"
}
}
Csv output ignores filtered field, so user will not
see that some data was not available.
strict=True
{
"errors": {
"geo": [
"incorrect definitions of geos"
]
}
}
Even if csv output was selected, error are reported in json format.