Ini adalah panduan developer untuk Analytics Reporting API v4. Untuk referensi API yang terperinci, lihat Referensi API.
Laporan
Analytics Reporting API v4 menyediakan metode batchGet untuk mengakses resource Reports.
Bagian berikut menjelaskan struktur isi permintaan
untuk batchGet
dan struktur isi respons dari batchGet
.
Isi Permintaan
Untuk menggunakan Analytics Reporting API v4 guna meminta data, Anda harus membuat objek ReportRequest, yang memiliki persyaratan minimum berikut:
- ID tampilan yang valid untuk kolom viewId.
- Minimal satu entri yang valid di kolom dateRanges.
- Minimal satu entri yang valid di kolom metrics.
Untuk menemukan ID tampilan, buat kueri metode account summary atau gunakan Account Explorer.
Jika rentang tanggal tidak diberikan, rentang tanggal default adalah:
{"startDate": "7daysAgo", "endDate": "yesterday"}
.
Berikut adalah contoh permintaan dengan kolom wajib diisi minimum:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
Metode batchGet
menerima maksimum lima objek ReportRequest. Semua permintaan harus memiliki
dateRange
,
viewId
,
segments
,
samplingLevel
,
dan cohortGroup
yang sama.
Isi Respons
Isi respons permintaan API adalah array objek Report. Struktur laporan ditentukan dalam objek ColumnHeader yang mendeskripsikan dimensi dan metrik serta jenis datanya dalam laporan. Nilai dimensi dan metrik ditentukan dalam kolom data.
Berikut adalah contoh respons untuk contoh permintaan di atas:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Metrik
Metrik merupakan pengukuran kuantitatif; setiap permintaan memerlukan setidaknya satu objek Metrik.
Pada contoh berikut, metrik Sessions
dimasukkan ke metode batchGet
untuk mendapatkan jumlah total sesi dalam rentang tanggal yang ditentukan:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Anda dapat menggunakan penjelajah dimensi dan metrik atau Metadata API untuk mendapatkan daftar dimensi dan metrik yang tersedia.
Pemfilteran
Saat mengirimkan permintaan batchGet
, Anda dapat memintanya untuk hanya menampilkan metrik yang memenuhi kriteria tertentu. Untuk memfilter metrik, dalam isi permintaan,
tentukan satu atau beberapa MetricFilterClauses dan
di setiap MetricFilterClause
, tentukan satu atau beberapa MetricFilters.
Di setiap MetricFilter
, tentukan nilai untuk hal berikut:
metricName
not
operator
comparisonValue
Biarkan {metricName}
mewakili metrik, {operator}
operator
, dan
{comparisonValue}
comparisonValue
. Kemudian, filter berfungsi seperti berikut:
if {metricName} {operator} {comparisonValue}
return the metric
Jika Anda menentukan true
untuk not
, filter akan berfungsi sebagai berikut:
if {metricName} {operator} {comparisonValue}
do not return the metric
Dalam contoh berikut, batchGet
hanya menampilkan kunjungan halaman yang nilainya lebih besar dari 2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Ekspresi
Ekspresi metrik adalah ekspresi matematika yang Anda tentukan pada metrik yang ada; ekspresi ini beroperasi seperti metrik kalkulasi dinamis. Anda dapat menentukan alias untuk mewakili ekspresi metrik, misalnya:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Pengurutan
Untuk mengurutkan hasil menurut nilai metrik:
- Masukkan nama atau aliasnya melalui kolom
fieldName
. - Tentukan tata urutan (
ASCENDING
atauDESCENDING
) melalui kolomsortOrder
.
Dalam contoh berikut, batchGet
menampilkan metrik yang diurutkan terlebih dahulu menurut sesi, lalu menurut kunjungan halaman dalam urutan menurun:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Dimensi
Dimensi menggambarkan karakteristik pengguna, serta sesi dan tindakan mereka.
Dimensi Kota, misalnya, menggambarkan karakteristik sesi dan
menunjukkan kota ("Paris" atau "New York") tempat setiap sesi berasal.
Dalam permintaan batchGet
, Anda dapat menentukan nol atau beberapa objek dimensi, misalnya:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Pemfilteran
Saat mengirimkan permintaan batchGet
, Anda dapat memintanya untuk hanya menampilkan
dimensi yang memenuhi kriteria tertentu. Untuk memfilter dimensi,
dalam isi permintaan, tentukan satu atau beberapa
DimensionsFilterClauses
dan di setiap DimensionsFilterClause
, tentukan satu atau beberapa
DimensionsFilters.
Di setiap DimensionsFilters
, tentukan nilai untuk hal berikut:
dimensionName
not
operator
expressions
caseSensitive
Biarkan {dimensionName}
mewakili dimensi, {operator}
untuk operator
, dan
{expressions}
expressions
. Kemudian, filter berfungsi seperti berikut:
if {dimensionName} {operator} {expressions}
return the dimension
Jika Anda menentukan true
untuk not
, filter akan berfungsi sebagai berikut:
if {dimensionName} {operator} {expressions}
do not return the dimension
Dalam contoh berikut, batchGet
menampilkan kunjungan halaman dan sesi di browser Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Pengurutan
Untuk mengurutkan hasil menurut nilai dimensi:
- Masukkan namanya melalui kolom
fieldName
. - Tentukan tata urutan (
ASCENDING
atauDESCENDING
) melalui kolomsortOrder
.
Misalnya, batchGet
berikut menampilkan dimensi yang diurutkan berdasarkan negara, lalu ditampilkan menurut browser:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Bucket histogram
Untuk dimensi dengan nilai bilangan bulat, akan lebih mudah untuk memahami karakteristiknya dengan mengelompokkan nilainya ke dalam rentang. Gunakan kolom
histogramBuckets
untuk menentukan rentang untuk bucket yang dihasilkan dan menentukan
HISTOGRAM_BUCKET
sebagai jenis urutan, misalnya:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Beberapa Rentang Tanggal
Google Analytics Reporting API v4 memungkinkan Anda mendapatkan data dalam beberapa rentang tanggal dalam satu permintaan. Baik permintaan Anda menetapkan satu atau dua rentang tanggal, data akan ditampilkan dalam objek dateRangeValue, misalnya:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Pengurutan Delta
Saat meminta nilai metrik dalam dua rentang tanggal, Anda dapat mengurutkan hasilnya berdasarkan perbedaan di antara nilai metrik dalam rentang tanggal, misalnya:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Perilaku dimensi tanggal
Jika Anda meminta dimensi terkait tanggal atau waktu, objek DateRangeValue hanya akan menyimpan nilai untuk tanggal yang berada dalam rentang masing-masing;
semua nilai lain yang tidak ada dalam rentang tanggal yang ditentukan akan menjadi 0
.
Misalnya, pertimbangkan permintaan untuk dimensi ga:date
dan metrik ga:sessions
dalam dua rentang tanggal: Januari dan Februari.
Sebagai respons untuk data yang diminta pada bulan Januari, nilai pada bulan Februari akan menjadi 0
; dan sebagai respons untuk data yang diminta pada bulan Februari, nilai pada bulan Januari akan menjadi 0
.
laporan Januari
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Laporan Februari
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmen
Untuk meminta subkumpulan data Analytics, gunakan segmen. Misalnya, Anda dapat menentukan pengguna dari negara atau kota tertentu dalam satu segmen, dan pengguna yang mengunjungi bagian tertentu situs Anda di segmen lainnya. Filter hanya menampilkan baris yang memenuhi kondisi, sedangkan segmen menampilkan subkumpulan pengguna, sesi, atau peristiwa yang memenuhi kondisi yang berisi segmen.
Saat membuat permintaan dengan segmen, pastikan bahwa:
- Setiap ReportRequest
dalam metode
batchGet
harus berisi definisi segmen yang identik. - Anda menambahkan
ga:segment
ke daftar dimensi.
Contoh:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Lihat Contoh untuk permintaan contoh lainnya dengan segmen.
ID segmen
Gunakan kolom segmentId
untuk meminta segmen.
Anda tidak dapat menggunakan segmentId
dan dynamicSegment
untuk meminta segmen.
Contoh:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Sampling
Pengambilan sampel dapat memengaruhi hasil data Anda dan merupakan alasan umum mengapa nilai yang ditampilkan dari API tidak cocok dengan antarmuka web. Gunakan kolom
samplingLevel
untuk menetapkan ukuran sampel yang diinginkan.
- Setel nilai ke
SMALL
untuk respons cepat dengan ukuran sampel yang lebih kecil. - setel nilai ke
LARGE
untuk respons yang lebih akurat namun lebih lambat. - Setel nilai ke
DEFAULT
untuk respons yang menyeimbangkan kecepatan dan akurasi.
Contoh:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
jika laporan berisi data sampel, Analytics Reporting API v4 akan menampilkan kolom samplesReadCounts
dan samplingSpaceSizes
.
Jika hasilnya tidak diambil sampelnya, kolom ini tidak akan ditentukan.
Berikut adalah contoh respons yang berisi sampel data dari permintaan dengan dua rentang tanggal. Hasil dihitung dari hampir 500 ribu sampel dengan ukuran ruang pengambilan sampel sekitar 15 juta sesi:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Penomoran halaman
Analytics Reporting API v4 menggunakan kolom pageToken
dan pageSize
untuk memberi nomor halaman melalui hasil respons yang mencakup beberapa halaman. Anda mendapatkan pageToken
dari
parameter nextPageToken
sebagai respons terhadap
permintaan reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Langkah berikutnya
Setelah Anda mempelajari dasar-dasar pembuatan laporan, lihat fitur lanjutan API v4.