Membuat Laporan

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 atau DESCENDING) melalui kolom sortOrder.

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 atau DESCENDING) melalui kolom sortOrder.

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.