# Instagram Insights API

# Instagram Insights

#  

<table id="bkmrk-informasi-keterangan"><tbody><tr><th>Informasi</th><th>Keterangan</th></tr><tr><td>Nama API</td><td>Instagram Insights API</td></tr><tr><td>Platform</td><td>Express.js, React, MySQL</td></tr><tr><td>Environment</td><td>Development &amp; Production</td></tr><tr><td>Production URL</td><td><code>https&#58;&#47;&#47;dev&#46;ncrsport&#46;com&#47;ig&#95;insights&#47;api</code></td></tr><tr><td>Format Response</td><td>JSON / CSV</td></tr><tr><td>Metode HTTP</td><td>GET, POST</td></tr><tr><td>Versi Dokumentasi</td><td>1.0</td></tr><tr><td>Terakhir Diperbarui</td><td>4 November 2026</td></tr></tbody></table>

<div id="bkmrk-">---

</div>## 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.

<div id="bkmrk--1">---

</div>## 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

<table id="bkmrk-method-endpoint-kete"><tbody><tr><th>Method</th><th>Endpoint</th><th>Keterangan</th></tr><tr><td>GET</td><td><code>&#47;api&#47;dashboard</code></td><td>Mengambil data dashboard Instagram</td></tr><tr><td>POST</td><td><code>&#47;api&#47;sync</code></td><td>Sinkronisasi data Instagram</td></tr><tr><td>GET</td><td><code>&#47;api&#47;export</code></td><td>Export data snapshot CSV</td></tr></tbody></table>

**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
```

<div id="bkmrk--2">---

</div>## 3. API Dashboard Instagram

### 3.1 Informasi Endpoint

<table id="bkmrk-informasi-keterangan-1"><tbody><tr><th>Informasi</th><th>Keterangan</th></tr><tr><td>Endpoint</td><td><code>&#47;api&#47;dashboard</code></td></tr><tr><td>Method</td><td>GET</td></tr><tr><td>Response</td><td>application/json</td></tr><tr><td>Fungsi</td><td>Mengambil statistik dan data konten Instagram</td></tr></tbody></table>

**Production URL:**

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

### 3.2 Query Parameters

<table id="bkmrk-parameter-wajib-defa"><tbody><tr><th>Parameter</th><th>Wajib</th><th>Default</th><th>Keterangan</th></tr><tr><td><code>from</code></td><td>Tidak</td><td>Awal bulan berjalan</td><td>Tanggal awal <code>YYYY&#45;MM&#45;DD</code></td></tr><tr><td><code>to</code></td><td>Tidak</td><td>Hari ini</td><td>Tanggal akhir <code>YYYY&#45;MM&#45;DD</code></td></tr><tr><td><code>month</code></td><td>Tidak</td><td>Bulan berjalan</td><td>Fallback periode <code>YYYY&#45;MM</code></td></tr><tr><td><code>account</code></td><td>Tidak</td><td>Semua akun</td><td>Filter username Instagram</td></tr><tr><td><code>search</code></td><td>Tidak</td><td>Kosong</td><td>Pencarian caption atau username</td></tr><tr><td><code>page</code></td><td>Tidak</td><td>1</td><td>Nomor halaman</td></tr><tr><td><code>pageSize</code></td><td>Tidak</td><td>10</td><td>Jumlah data per halaman, maksimal 100</td></tr></tbody></table>

### 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

<table id="bkmrk-field-keterangan-fro"><tbody><tr><th>Field</th><th>Keterangan</th></tr><tr><td><code>from</code></td><td>Tanggal awal periode</td></tr><tr><td><code>to</code></td><td>Tanggal akhir periode</td></tr><tr><td><code>aggregation</code></td><td>Metode agregasi metrik</td></tr><tr><td><code>contentCount</code></td><td>Total konten sesuai filter</td></tr><tr><td><code>totals</code></td><td>Akumulasi metrik Instagram</td></tr><tr><td><code>accounts</code></td><td>Daftar akun Instagram</td></tr><tr><td><code>media</code></td><td>Data detail sesuai pagination</td></tr><tr><td><code>summaryMedia</code></td><td>Seluruh data hasil filter</td></tr><tr><td><code>topContent</code></td><td>Konten dengan performa terbaik</td></tr><tr><td><code>dailyTrend</code></td><td>Data tren harian</td></tr><tr><td><code>comparison</code></td><td>Perbandingan periode sebelumnya</td></tr><tr><td><code>pagination</code></td><td>Informasi pagination</td></tr></tbody></table>

### 3.7 Penjelasan Metrik

<table id="bkmrk-metric-keterangan-vi"><tbody><tr><th>Metric</th><th>Keterangan</th></tr><tr><td><code>views</code></td><td>Jumlah tayangan konten</td></tr><tr><td><code>reach</code></td><td>Jumlah akun yang dijangkau</td></tr><tr><td><code>likes</code></td><td>Jumlah likes</td></tr><tr><td><code>comments</code></td><td>Jumlah komentar</td></tr><tr><td><code>shares</code></td><td>Jumlah pembagian konten</td></tr><tr><td><code>follows</code></td><td>Jumlah follows</td></tr><tr><td><code>saves</code></td><td>Jumlah penyimpanan konten</td></tr></tbody></table>

**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.

<div id="bkmrk--3">---

</div>## 4. API Sinkronisasi Instagram

### 4.1 Informasi Endpoint

<table id="bkmrk-informasi-keterangan-2"><tbody><tr><th>Informasi</th><th>Keterangan</th></tr><tr><td>Endpoint</td><td><code>&#47;api&#47;sync</code></td></tr><tr><td>Method</td><td>POST</td></tr><tr><td>Content-Type</td><td>application/json</td></tr><tr><td>Fungsi</td><td>Mengambil dan menyimpan data Instagram terbaru</td></tr></tbody></table>

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"
}
```

<table id="bkmrk-field-wajib-keterang"><tbody><tr><th>Field</th><th>Wajib</th><th>Keterangan</th></tr><tr><td><code>targetMonth</code></td><td>Tidak</td><td>Bulan media yang diambil, <code>YYYY&#45;MM</code></td></tr><tr><td><code>snapshotDate</code></td><td>Tidak</td><td>Tanggal snapshot, <code>YYYY&#45;MM&#45;DD</code></td></tr></tbody></table>

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"
}
```

<table id="bkmrk-field-keterangan-pos"><tbody><tr><th>Field</th><th>Keterangan</th></tr><tr><td><code>postsFetched</code></td><td>Jumlah konten yang berhasil diambil</td></tr><tr><td><code>errors</code></td><td>Jumlah error selama sinkronisasi</td></tr><tr><td><code>targetMonth</code></td><td>Bulan target sinkronisasi</td></tr></tbody></table>

### 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.

<div id="bkmrk--4">---

</div>## 5. API Export CSV

### 5.1 Informasi Endpoint

<table id="bkmrk-informasi-keterangan-3"><tbody><tr><th>Informasi</th><th>Keterangan</th></tr><tr><td>Endpoint</td><td><code>&#47;api&#47;export</code></td></tr><tr><td>Method</td><td>GET</td></tr><tr><td>Response</td><td>text/csv</td></tr><tr><td>Fungsi</td><td>Mengunduh data snapshot Instagram</td></tr></tbody></table>

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

Data export tidak dibatasi oleh pagination.

### 5.2 Query Parameters

<table id="bkmrk-parameter-wajib-defa-1"><tbody><tr><th>Parameter</th><th>Wajib</th><th>Default</th><th>Keterangan</th></tr><tr><td><code>from</code></td><td>Tidak</td><td>Awal bulan berjalan</td><td>Tanggal awal</td></tr><tr><td><code>to</code></td><td>Tidak</td><td>Hari ini</td><td>Tanggal akhir</td></tr><tr><td><code>account</code></td><td>Tidak</td><td>Semua akun</td><td>Filter username</td></tr><tr><td><code>search</code></td><td>Tidak</td><td>Kosong</td><td>Pencarian konten</td></tr></tbody></table>

### 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.

<div id="bkmrk--5">---

</div>## 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.

<div id="bkmrk--6">---

</div>## 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:**

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.

<div id="bkmrk--7">---

</div>## 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.

<div id="bkmrk--8">---

</div>## 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.

<div id="bkmrk--9">---

</div>## 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.

<div id="bkmrk--10">---

</div>**NCR Sport — IT Department**

*Dokumentasi Internal \| Instagram Insights API \| November 2026*