Instagram Insights API 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: 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