Instagram Insights API

Instagram Insights

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:

Periksa file .env.
Pastikan format JSON valid.
Pastikan username dan account ID sesuai data yang di-import.
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:

Pastikan service Express berjalan melalui PM2.
Pastikan koneksi database MySQL tersedia.
Pastikan konfigurasi akun Instagram sesuai kebutuhan.
Periksa validitas access token Graph API secara berkala.
Monitor log aplikasi ketika proses sinkronisasi gagal.
Batasi akses endpoint sinkronisasi pada environment production.
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