Membuat Laporan

Ini adalah panduan developer untuk Analytics Reporting API v4. Untuk referensi API yang mendetail, lihat Referensi API.

Catatan: API ini tidak mendukung properti Google Analytics 4 (GA4). Gunakan Google Analytics Data API guna mengakses fitur pelaporan baru untuk properti GA4.

Laporan

Analytics Reporting API v4 menyediakan metode batchGet untuk mengakses resource Laporan. Bagian berikut menjelaskan struktur isi permintaan untuk batchGet dan struktur isi respons dari batchGet.

Isi Permintaan

Untuk menggunakan Analytics Reporting API v4 untuk meminta data, Anda harus membuat objek ReportRequest, yang memiliki persyaratan minimum berikut:

• ID tampilan yang valid untuk kolom viewId.
• Setidaknya satu entri yang valid di kolom dateRanges.
• Setidaknya satu entri yang valid di kolom metrics.

Untuk menemukan ID tampilan, kueri metode ringkasan akun atau gunakan Account Explorer. Jika rentang tanggal tidak ditentukan, rentang tanggal default-nya adalah: {"startDate": "7daysAgo", "endDate": "yesterday"}.

Berikut adalah contoh permintaan dengan kolom minimum yang wajib diisi:

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 Laporan. 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"
                        ]
                    }
                ]
            }
        }
    ]
}

Catatan: Saat menguraikan isi respons, jika kolom boolean tidak ada, Anda dapat mengasumsikan nilainya adalah false. Hanya kolom boolean dengan nilai true yang ditampilkan dalam respons; misalnya, kolom isDataGolden akan ada dalam respons jika nilainya true.

Metrik

Metrik adalah pengukuran kuantitatif; setiap permintaan memerlukan setidaknya satu objek Metrik.

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, di 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

Izinkan {metricName} mewakili metrik, {operator} operator, dan {comparisonValue} comparisonValue. Kemudian filternya berfungsi sebagai berikut:

if {metricName} {operator} {comparisonValue}
   return the metric

Jika Anda menentukan true untuk not, maka filter akan berfungsi seperti berikut:

if {metricName} {operator} {comparisonValue}
   do not return the metric

Pada 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; operasi 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"
        }
      ]
    }
  ]
}

Catatan: Anda juga dapat menentukan jenis pemformatan untuk ekspresi metrik yang Anda tentukan.

Pengurutan

Untuk mengurutkan hasil menurut nilai metrik:

• Berikan nama atau aliasnya melalui kolom fieldName.
• Tentukan tata urutan (ASCENDING atau DESCENDING) melalui kolom sortOrder.

Pada contoh berikut, batchGet menampilkan metrik yang diurutkan terlebih dahulu berdasarkan 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, menjelaskan 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, di isi permintaan, tentukan satu atau beberapa DimensionFilterClauses dan di setiap DimensionsFilterClause, tentukan satu atau beberapa DimensionFilters. Di setiap DimensionsFilters, tentukan nilai untuk hal berikut:

• dimensionName
• not
• operator
• expressions
• caseSensitive

Izinkan {dimensionName} mewakili dimensi, {operator} operator, dan {expressions} expressions. Kemudian filternya berfungsi sebagai berikut:

if {dimensionName} {operator} {expressions}
    return the dimension

Jika Anda menentukan true untuk not, maka filter akan berfungsi seperti 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:

• Berikan namanya melalui kolom fieldName.
• Tentukan tata urutan (ASCENDING atau DESCENDING) melalui kolom sortOrder.

Misalnya, batchGet berikut akan menampilkan dimensi yang diurutkan berdasarkan negara, kemudian 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, lebih mudah untuk memahami karakteristiknya dengan mengelompokkan nilainya ke dalam rentang. Gunakan kolom histogramBuckets untuk menentukan rentang bucket yang dihasilkan dan menentukan HISTOGRAM_BUCKET sebagai jenis pesanan, 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"
        }
      ]
    }
  ]
}

Catatan: Lihat Request Composer untuk aplikasi demo yang memanfaatkan beberapa fitur ini.

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 hasil menurut 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 terkait; semua nilai lainnya yang tidak berada dalam rentang tanggal yang ditentukan adalah 0.

Misalnya, pertimbangkan permintaan untuk dimensi ga:date dan metrik ga:sessions dalam dua rentang tanggal: Januari dan Februari. Dalam respons untuk data yang diminta pada bulan Januari, nilai pada bulan Februari adalah 0; dan sebagai respons untuk data yang diminta pada bulan Februari, nilai pada bulan Januari adalah 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 Anda, gunakan segmen. Misalnya, Anda dapat menentukan pengguna dari negara atau kota tertentu di 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 contoh permintaan 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"}]
    }
  ]
}

Catatan: Kolom segmentId juga mendukung sintaksis segmen di Core Reporting API V3. Lihat Panduan Migrasi untuk mengetahui detailnya.

Pengambilan sampel

Catatan: Untuk akun Analytics 360, pertimbangkan untuk menggunakan fitur Kuota Berbasis Resource untuk memanfaatkan nilai minimum pengambilan sampel yang lebih tinggi saat menggunakan Analytics Reporting API.

Pengambilan sampel dapat memengaruhi hasil data Anda dan merupakan alasan umum mengapa nilai yang ditampilkan API tidak cocok dengan antarmuka web. Gunakan kolom samplingLevel untuk menetapkan ukuran sampel yang diinginkan.

• Setel nilai ke SMALL untuk respons cepat dengan ukuran pengambilan sampel yang lebih kecil.
• setel nilai ke LARGE untuk mendapatkan 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"
    }
  ]
}

Catatan: Setiap ReportRequest dalam metode batchGet harus berisi definisi samplingLevel yang sama.

jika laporan berisi data sampel Analytics Analytics API v4 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 penomoran 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",
  }]
}

Catatan: Secara teknis, nextPageToken dapat berupa string arbitrer, tetapi dalam kebanyakan kasus, ini adalah indeks baris berbasis nol. Untuk memastikan penomoran halaman yang tepat, gunakan nilai nextPageToken untuk kolom pageToken.

Langkah berikutnya

Setelah membahas dasar-dasar pembuatan laporan, lihat fitur lanjutan API v4'