Ini adalah panduan developer untuk Analytics Reporting API v4. Untuk referensi API yang mendetail, 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 ringkasan akun 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 di 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 Metric.
Pada contoh berikut, metrik Sessions
diberikan 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
Misalkan {metricName}
mewakili metrik, {operator}
sebagai operator
, dan
{comparisonValue}
adalah comparisonValue
. Kemudian, filter berfungsi sebagai 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 yang dihitung 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 pertama kali berdasarkan sesi, kemudian 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
Misalkan {dimensionName}
mewakili dimensi, {operator}
sebagai operator
, dan
{expressions}
adalah expressions
. Kemudian, filter berfungsi sebagai 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 menampilkan dimensi yang diurutkan berdasarkan 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, karakteristiknya akan lebih mudah dipahami dengan mengelompokkan nilainya ke dalam rentang. Gunakan kolom histogramBuckets
untuk menentukan rentang 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 menentukan 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 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 dalam respons untuk data yang diminta pada bulan Februari,
nilai pada bulan Januari akan menjadi 0
.
Laporan bulan 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 di situs Anda di segmen yang lain. 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:
- 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 mengetahui contoh permintaan lainnya dengan segmen.
ID segmen
Gunakan kolom segmentId
untuk meminta segmen.
Anda tidak dapat menggunakan segmentId
dan dynamicSegment
secara bersamaan 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"}]
}
]
}
Pengambilan Sampel
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 tetapi 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 sampel data, 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. Hasilnya dihitung dari hampir 500 ribu sampel 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 pada 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.