Skip to main content

Instagram Insights

 

Informasi Keterangan
Nama API Instagram Insights API
Platform Express.js, React, MySQL
Environment Development & Production
Production URL https://dev.ncrsport.com/ig_insights/api
Format Response JSON / CSV
Metode HTTP GET, POST
Versi Dokumentasi 1.0
Terakhir Diperbarui 4 November 2026

1. Pendahuluan

1.1 Deskripsi

Instagram Insights API merupakan layanan backend berbasis Express.js yang digunakan untuk menyediakan data analitik Instagram kepada dashboard React.

API mengambil data dari database MySQL yang menyimpan informasi media Instagram beserta snapshot metrik performanya.

Data dashboard dihitung menggunakan metrik accumulated_* dari tabel InstagramMediaSnapshot, sehingga informasi yang ditampilkan merupakan hasil agregasi berdasarkan periode yang dipilih.

1.2 Fitur Utama

  • Dashboard statistik performa Instagram.

  • Filter berdasarkan tanggal dan akun Instagram.

  • Pencarian konten berdasarkan caption atau username.

  • Pagination untuk data detail konten.

  • Sinkronisasi data melalui Facebook Graph API.

  • Perbandingan performa dengan periode sebelumnya.

  • Export data snapshot ke format CSV.

  • Statistik Content Pillar dan Top Content.

2. Konfigurasi API

2.1 Base URL

Development — Express

http://localhost:3001/api

Development — Vite Proxy

http://localhost:5173/api

Production

https://dev.ncrsport.com/ig_insights/api

2.2 Daftar Endpoint

Method Endpoint Keterangan
GET /api/dashboard Mengambil data dashboard Instagram
POST /api/sync Sinkronisasi data Instagram
GET /api/export Export data snapshot CSV

Catatan: Pada production, gunakan prefix /ig_insights/api sebagai pengganti /api.

2.3 Konfigurasi Akun Instagram

Akun yang ditampilkan pada dashboard dibatasi berdasarkan konfigurasi environment variable IG_ACCOUNTS_JSON.

Contoh konfigurasi pada .env:

IG_ACCOUNTS_JSON='[{"id":"17841402099215864","username":"ncr_rackets","name":"NCR Rackets"}]'

Akun yang telah di-import dari ERP tetapi tidak terdaftar pada konfigurasi tersebut tidak akan ditampilkan di dashboard.

Setelah mengubah konfigurasi, jalankan:

pm2 restart instagram-insights-api --update-env

3. API Dashboard Instagram

3.1 Informasi Endpoint

Informasi Keterangan
Endpoint /api/dashboard
Method GET
Response application/json
Fungsi Mengambil statistik dan data konten Instagram

Production URL:

https://dev.ncrsport.com/ig_insights/api/dashboard

3.2 Query Parameters

Parameter Wajib Default Keterangan
from Tidak Awal bulan berjalan Tanggal awal YYYY-MM-DD
to Tidak Hari ini Tanggal akhir YYYY-MM-DD
month Tidak Bulan berjalan Fallback periode YYYY-MM
account Tidak Semua akun Filter username Instagram
search Tidak Kosong Pencarian caption atau username
page Tidak 1 Nomor halaman
pageSize Tidak 10 Jumlah data per halaman, maksimal 100

3.3 Contoh Request

A. Mengambil seluruh data dashboard

GET /api/dashboard

B. Filter berdasarkan periode

GET /api/dashboard?from=2026-11-01&to=2026-11-04

C. Filter berdasarkan akun

GET /api/dashboard?from=2026-11-01&to=2026-11-04&account=ncr_rackets

D. Pencarian dan pagination

GET /api/dashboard?from=2026-11-01&to=2026-11-04&search=promo&page=2&pageSize=10

3.4 Contoh cURL

curl -X GET \
  "https://dev.ncrsport.com/ig_insights/api/dashboard?from=2026-11-01&to=2026-11-04" \
  -H "Accept: application/json"

Untuk menampilkan response lebih mudah dibaca:

curl -s \
  "http://127.0.0.1:3001/api/dashboard?from=2026-11-01&to=2026-11-04" | jq

3.5 Contoh Response

HTTP 200 OK

{
  "from": "2026-11-01",
  "to": "2026-11-04",
  "aggregation": "accumulated",
  "contentCount": 42,
  "totals": {
    "views": 120000,
    "reach": 85000,
    "likes": 3200,
    "comments": 410,
    "shares": 800,
    "follows": 120,
    "saves": 650
  },
  "accounts": [],
  "media": [],
  "summaryMedia": [],
  "topContent": [],
  "dailyTrend": [],
  "comparison": {
    "previousPeriod": {
      "from": "2026-10-28",
      "to": "2026-10-31",
      "content_count": 39,
      "views": 95000,
      "reach": 70000,
      "likes": 2500,
      "comments": 300,
      "shares": 500,
      "follows": 80,
      "saves": 400
    }
  },
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 42,
    "pageCount": 5
  }
}

Response di atas merupakan contoh ilustrasi, bukan data aktual production.

3.6 Penjelasan Response

Field Keterangan
from Tanggal awal periode
to Tanggal akhir periode
aggregation Metode agregasi metrik
contentCount Total konten sesuai filter
totals Akumulasi metrik Instagram
accounts Daftar akun Instagram
media Data detail sesuai pagination
summaryMedia Seluruh data hasil filter
topContent Konten dengan performa terbaik
dailyTrend Data tren harian
comparison Perbandingan periode sebelumnya
pagination Informasi pagination

3.7 Penjelasan Metrik

Metric Keterangan
views Jumlah tayangan konten
reach Jumlah akun yang dijangkau
likes Jumlah likes
comments Jumlah komentar
shares Jumlah pembagian konten
follows Jumlah follows
saves Jumlah penyimpanan konten

Penting:

Dashboard menggunakan nilai accumulated_* dari InstagramMediaSnapshot, bukan nilai raw_*.

3.8 Perbedaan Media dan SummaryMedia

media

Berisi data detail konten pada halaman yang sedang diakses. Jumlah data dipengaruhi oleh parameter page dan pageSize.

summaryMedia

Berisi seluruh konten yang memenuhi filter periode, akun, dan pencarian, tanpa pembatasan pagination.

Data ini digunakan untuk kebutuhan statistik agregat dan Content Pillar.

contentCount

Menunjukkan jumlah seluruh konten yang memenuhi filter, bukan jumlah konten pada halaman aktif.

pagination.total

Menunjukkan jumlah seluruh record detail yang sesuai dengan filter.

4. API Sinkronisasi Instagram

4.1 Informasi Endpoint

Informasi Keterangan
Endpoint /api/sync
Method POST
Content-Type application/json
Fungsi Mengambil dan menyimpan data Instagram terbaru

Endpoint ini mengambil data dari Facebook Graph API untuk akun yang terdaftar pada IG_ACCOUNTS_JSON.

Data yang berhasil diambil akan disimpan ke MySQL dalam bentuk data media dan snapshot.

4.2 Request Body

{
  "targetMonth": "2026-11",
  "snapshotDate": "2026-11-04"
}
Field Wajib Keterangan
targetMonth Tidak Bulan media yang diambil, YYYY-MM
snapshotDate Tidak Tanggal snapshot, YYYY-MM-DD

Jika request body tidak menyertakan kedua field tersebut:

  • snapshotDate menggunakan tanggal hari ini berdasarkan zona waktu Asia/Jakarta.

  • targetMonth menggunakan bulan dari tanggal snapshot.

4.3 Contoh Request cURL

curl -X POST \
  "http://127.0.0.1:3001/api/sync" \
  -H "Content-Type: application/json" \
  -d '{
    "targetMonth": "2026-11",
    "snapshotDate": "2026-11-04"
  }'

4.4 Contoh Response

{
  "postsFetched": 42,
  "errors": 0,
  "targetMonth": "2026-11"
}
Field Keterangan
postsFetched Jumlah konten yang berhasil diambil
errors Jumlah error selama sinkronisasi
targetMonth Bulan target sinkronisasi

4.5 Keamanan Endpoint Sync

Perhatian:

Endpoint /api/sync melakukan proses pengambilan data eksternal dan penyimpanan ke database.

Untuk penggunaan production, endpoint ini tidak disarankan dibuka bebas tanpa autentikasi.

Pengamanan yang dapat diterapkan:

  • Authentication middleware.

  • Pembatasan akses melalui reverse proxy.

  • VPN atau firewall.

  • Pembatasan IP yang diperbolehkan mengakses endpoint.

5. API Export CSV

5.1 Informasi Endpoint

Informasi Keterangan
Endpoint /api/export
Method GET
Response text/csv
Fungsi Mengunduh data snapshot Instagram

Endpoint export menghasilkan file CSV yang berisi data snapshot berdasarkan filter yang diberikan.

Data export tidak dibatasi oleh pagination.

5.2 Query Parameters

Parameter Wajib Default Keterangan
from Tidak Awal bulan berjalan Tanggal awal
to Tidak Hari ini Tanggal akhir
account Tidak Semua akun Filter username
search Tidak Kosong Pencarian konten

5.3 Contoh Request

GET /api/export?from=2026-11-01&to=2026-11-04

Dengan filter akun:

GET /api/export?from=2026-11-01&to=2026-11-04&account=ncr_rackets

5.4 Contoh cURL

curl -L \
  "http://127.0.0.1:3001/api/export?from=2026-11-01&to=2026-11-04&account=ncr_rackets" \
  -o instagram-insights-2026-11-01-2026-11-04.csv

Production URL

https://dev.ncrsport.com/ig_insights/api/export?from=2026-11-01&to=2026-11-04

5.5 Informasi Data CSV

File export berisi:

  • Metadata konten Instagram.

  • Tanggal snapshot.

  • Raw metric.

  • Accumulated metric.

File CSV dapat digunakan untuk analisis tambahan melalui Microsoft Excel, Google Sheets, atau aplikasi pengolahan data lainnya.

6. Integrasi API dengan JavaScript

6.1 Mengambil Data Dashboard

Contoh penggunaan JavaScript Fetch API:

const params = new URLSearchParams({
  from: "2026-11-01",
  to: "2026-11-04",
  account: "ncr_rackets",
  page: "1",
  pageSize: "10",
});

const response = await fetch(
  `/ig_insights/api/dashboard?${params}`
);

const data = await response.json();

console.log(data.contentCount);
console.log(data.totals);
console.log(data.summaryMedia);

6.2 Akses Langsung ke Express

const response = await fetch(
  "http://localhost:3001/api/dashboard?from=2026-11-01&to=2026-11-04"
);

const data = await response.json();

console.log(data);

6.3 Contoh Sinkronisasi Menggunakan Fetch

const response = await fetch(
  "/ig_insights/api/sync",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      targetMonth: "2026-11",
      snapshotDate: "2026-11-04"
    })
  }
);

const result = await response.json();

console.log(result);

Catatan: Contoh di atas mengasumsikan endpoint sync dapat diakses oleh aplikasi. Pada production, ikuti mekanisme autentikasi yang diterapkan server.

7. Troubleshooting

7.1 Response HTML, Bukan JSON

Gejala:

API mengembalikan halaman HTML yang diawali dengan:

<!DOCTYPE html>

Kemungkinan penyebab:

Request diarahkan ke frontend Vite atau static file, bukan ke Express API.

Solusi:

Pastikan URL endpoint sesuai environment.

Development:

http://localhost:3001/api/dashboard

Vite Proxy:

http://localhost:5173/api/dashboard

Production:

https://dev.ncrsport.com/ig_insights/api/dashboard

7.2 Connection Refused

Gejala:

Request tidak dapat terhubung ke API.

Kemungkinan penyebab:

Service Express tidak berjalan atau port tidak dapat diakses.

Langkah pemeriksaan:

pm2 list

Lakukan pengujian API:

curl http://127.0.0.1:3001/api/dashboard

Jika service tidak berjalan, periksa konfigurasi dan status PM2.

7.3 Akun Instagram Tidak Muncul

Kemungkinan penyebab:

Akun tidak terdaftar pada environment variable IG_ACCOUNTS_JSON.

Solusi:

  1. Periksa file .env.

  2. Pastikan format JSON valid.

  3. Pastikan username dan account ID sesuai data yang di-import.

  4. Restart API setelah perubahan konfigurasi.

pm2 restart instagram-insights-api --update-env

7.4 Sinkronisasi Instagram Gagal

Kemungkinan penyebab:

  • Access token Instagram tidak valid atau kedaluwarsa.

  • Konfigurasi Graph API tidak sesuai.

  • Terjadi error saat request ke Facebook Graph API.

  • Terjadi kesalahan penyimpanan database.

Langkah pemeriksaan:

Periksa log aplikasi:

pm2 logs instagram-insights-api

Pastikan konfigurasi Graph API:

IG_GRAPH_BASE_URL="https://graph.facebook.com/v21.0"

Periksa kembali access token dan konfigurasi akun Instagram.

8. Pengujian API

8.1 Pengujian Dashboard

Jalankan:

curl -i \
  "https://dev.ncrsport.com/ig_insights/api/dashboard?from=2026-11-01&to=2026-11-04"

Pastikan:

  • Request berhasil.

  • Response menggunakan format JSON.

  • Data totals tersedia.

  • Data pagination sesuai parameter.

  • Filter periode berjalan sesuai request.

8.2 Pengujian Export

Buka URL berikut pada browser:

https://dev.ncrsport.com/ig_insights/api/export?from=2026-11-01&to=2026-11-04

Pastikan file CSV dapat diunduh dan berisi data sesuai periode yang dipilih.

8.3 Pengujian Sync

Lakukan request POST menggunakan Postman atau cURL dari lingkungan yang diizinkan.

Pastikan response mengembalikan informasi:

{
  "postsFetched": 42,
  "errors": 0,
  "targetMonth": "2026-11"
}

Nilai pada response dapat berbeda sesuai jumlah konten dan hasil sinkronisasi.

9. Catatan Operasional

Untuk menjaga stabilitas aplikasi Instagram Insights:

  1. Pastikan service Express berjalan melalui PM2.

  2. Pastikan koneksi database MySQL tersedia.

  3. Pastikan konfigurasi akun Instagram sesuai kebutuhan.

  4. Periksa validitas access token Graph API secara berkala.

  5. Monitor log aplikasi ketika proses sinkronisasi gagal.

  6. Batasi akses endpoint sinkronisasi pada environment production.

  7. Gunakan endpoint export untuk kebutuhan analisis data di luar dashboard.

10. Informasi Dukungan

Dokumentasi ini digunakan sebagai panduan teknis penggunaan dan integrasi Instagram Insights API pada lingkungan NCR Sport.

Apabila mengalami kendala saat mengakses API, melakukan sinkronisasi Instagram, atau menemukan ketidaksesuaian data pada dashboard, silakan menghubungi Tim IT NCR Sport untuk pemeriksaan lebih lanjut.

NCR Sport — IT Department

Dokumentasi Internal | Instagram Insights API | November 2026

No comments to display