REST API
Create a new page view tracking entry for an article.
POST
{{baseUrl}}/v1/analytics/trackAuth required
Request Body
| Property | Type | Description | Default |
|---|---|---|---|
slug* | string | Article slug (required) | - |
sessionId | string | User session identifier | - |
pageUrl | string | Full page URL | - |
pageTitle | string | Page title | - |
referrer | string | Referrer URL | - |
utmSource | string | UTM source parameter | - |
utmMedium | string | UTM medium parameter | - |
utmCampaign | string | UTM campaign parameter | - |
utmTerm | string | UTM term parameter | - |
utmContent | string | UTM content parameter | - |
screenWidth | number | Screen width in pixels | - |
screenHeight | number | Screen height in pixels | - |
timeOnPage | number | Time spent in seconds | - |
scrollDepth | number | Scroll depth (0-100%) | - |
exitPosition | number | Exit position (0-100%) | - |
bounced | boolean | Whether user bounced | - |
events | PageEvent[] | Custom events array | - |
fetchGeo | boolean | Fetch geolocation data | - |
| Property | Type | Description | Default |
|---|---|---|---|
id* | string | Page view tracking ID | - |
success* | boolean | Whether tracking succeeded | - |
cURL Command
curl -X POST "https://api.simplist.blog/v1/analytics/track" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"slug\":\"getting-started\",\"sessionId\":\"sess_abc123\",\"pageUrl\":\"https://myblog.com/blog/getting-started\",\"timeOnPage\":0,\"fetchGeo\":true}"minimal-example.json{
"slug": "getting-started"
}complete-example.json{
"slug": "getting-started",
"sessionId": "sess_abc123",
"pageUrl": "https://myblog.com/blog/getting-started",
"pageTitle": "Getting Started with Simplist",
"referrer": "https://google.com",
"utmSource": "google",
"utmMedium": "cpc",
"utmCampaign": "launch",
"screenWidth": 1920,
"screenHeight": 1080,
"timeOnPage": 0,
"scrollDepth": 0,
"exitPosition": 0,
"bounced": false,
"fetchGeo": true,
"events": []
}response.json{
"success": true,
"pageViewId": "pv_xyz789",
"visitorId": "visitor_def456",
"sessionId": "session_abc123"
}- Initialize tracking when user lands on page (timeOnPage: 0)
- Store the page view ID returned in response
- Update metrics periodically using PUT/v1/analytics/track/:id
- Send final update when user leaves (with final timeOnPage, scrollDepth, etc.)
- Server-side analytics: Track views without JavaScript
- Privacy-friendly tracking: No cookies, no client-side scripts
- Custom events: Track button clicks, video plays, etc.
- UTM tracking: Campaign attribution
- Geolocation: Optional IP-based location (GDPR compliant)
If you're using TypeScript/JavaScript, you can use the SDK instead: client.analytics.track()
Notes
Session ID:Generate a unique ID per user session (e.g., UUID)
Geolocation:Only fetched if fetchGeo: true (based on IP address)
Privacy:All data is anonymized and GDPR compliant
Update:Use the returned id to update metrics with PUT request