Analytics Endpoints

The Analytics API provides read access to all your website analytics data. Use these endpoints to build custom dashboards, generate reports, or integrate DataSaaS data into your own tools.

Authentication

All analytics endpoints require a valid API key passed via the Authorization header.

curl -H "Authorization: Bearer ds_live_xxxxx" \
  "https://datasaas.co/api/v1/overview?site_id=ds_abc123"

Common parameters

Every analytics endpoint accepts the following query parameters:

Parameter	Type	Required	Description
`site_id`	string	Yes	Your website ID (e.g., `ds_abc123`)
`start`	string	No	ISO 8601 start date. Default: 30 days ago
`end`	string	No	ISO 8601 end date. Default: now
`timezone`	string	No	IANA timezone (e.g., `America/New_York`). Default: UTC
`limit`	number	No	Results limit, 1–1000. Default: 100

Endpoints

GET /api/v1/overview

Returns aggregate metrics for your website within the given date range, including visitors, pageviews, bounce rate, average session duration, revenue, MRR, and conversion rate.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/overview?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"

{
  "results": {
    "visitors": 12453,
    "pageviews": 34211,
    "bounce_rate": 0.42,
    "avg_duration": 187,
    "revenue": 24500.00,
    "mrr": 8200.00,
    "conversion_rate": 0.032
  },
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "timezone": "UTC"
  }
}

GET /api/v1/timeseries

Returns time series data broken down by the specified granularity. Useful for rendering charts and tracking trends over time.

Parameter	Type	Required	Description
`granularity`	string	No	One of `hour`, `day`, `week`, `month`. Default: `day`

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/timeseries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&granularity=day"

{
  "results": [
    { "period": "2026-03-01", "visitors": 421, "pageviews": 1230 },
    { "period": "2026-03-02", "visitors": 389, "pageviews": 1102 },
    { "period": "2026-03-03", "visitors": 455, "pageviews": 1345 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "granularity": "day"
  }
}

GET /api/v1/pages

Returns the top pages on your website ranked by pageviews. Includes the pathname, total pageviews, and unique visitors for each page.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "pathname": "/", "pageviews": 5000, "visitors": 3200 },
    { "pathname": "/pricing", "pageviews": 2100, "visitors": 1800 },
    { "pathname": "/docs", "pageviews": 1500, "visitors": 1100 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/entry-pages

Returns the pages where visitors first land on your website. Entry pages are determined by the first pageview in each session.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/entry-pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "entry_page": "/", "visitors": 2800 },
    { "entry_page": "/blog/analytics-guide", "visitors": 950 },
    { "entry_page": "/pricing", "visitors": 720 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/exit-pages

Returns the pages where visitors leave your website. Exit pages are determined by the last pageview in each session.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/exit-pages?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "exit_page": "/pricing", "visitors": 1200 },
    { "exit_page": "/", "visitors": 980 },
    { "exit_page": "/checkout", "visitors": 540 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/referrers

Returns traffic sources (referrer domains) ranked by the number of visitors they sent to your website. Direct traffic appears as an empty string.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/referrers?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "referrer": "google.com", "visitors": 4500 },
    { "referrer": "twitter.com", "visitors": 1200 },
    { "referrer": "github.com", "visitors": 800 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/channels

Returns traffic grouped by marketing channel (e.g., Organic Search, Paid Search, Social, Direct, Referral, Email). Channels are automatically classified based on referrer and UTM parameters.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/channels?site_id=ds_abc123&start=2026-03-01&end=2026-03-26"

{
  "results": [
    { "channel": "Organic Search", "visitors": 6000 },
    { "channel": "Direct", "visitors": 3200 },
    { "channel": "Social", "visitors": 1800 },
    { "channel": "Referral", "visitors": 900 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z"
  }
}

GET /api/v1/campaigns

Returns UTM campaign data grouped by campaigns, sources, mediums, and contents. Only visitors with UTM parameters are included.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/campaigns?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": {
    "campaigns": [
      { "campaign": "spring_sale", "visitors": 2400, "pageviews": 5800 },
      { "campaign": "product_launch", "visitors": 1100, "pageviews": 3200 }
    ],
    "sources": [
      { "source": "google", "visitors": 3200 },
      { "source": "facebook", "visitors": 1400 }
    ],
    "mediums": [
      { "medium": "cpc", "visitors": 2800 },
      { "medium": "email", "visitors": 1200 }
    ],
    "contents": [
      { "content": "hero_banner", "visitors": 900 },
      { "content": "sidebar_ad", "visitors": 600 }
    ]
  },
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/countries

Returns a breakdown of visitors by country, ranked by visitor count.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/countries?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "country": "United States", "visitors": 8000 },
    { "country": "United Kingdom", "visitors": 1500 },
    { "country": "Germany", "visitors": 900 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/regions

Returns a breakdown of visitors by region (state or province).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/regions?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "region": "California", "visitors": 2000 },
    { "region": "New York", "visitors": 1400 },
    { "region": "Texas", "visitors": 1100 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/cities

Returns a breakdown of visitors by city.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/cities?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "city": "San Francisco", "visitors": 800 },
    { "city": "New York", "visitors": 750 },
    { "city": "London", "visitors": 620 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/browsers

Returns a breakdown of visitors by web browser.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/browsers?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "browser": "Chrome", "visitors": 7000 },
    { "browser": "Safari", "visitors": 3200 },
    { "browser": "Firefox", "visitors": 1400 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/os

Returns a breakdown of visitors by operating system.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/os?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "os": "macOS", "visitors": 5000 },
    { "os": "Windows", "visitors": 4200 },
    { "os": "iOS", "visitors": 1800 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

GET /api/v1/devices

Returns a breakdown of visitors by device type (desktop, mobile, or tablet).

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://datasaas.co/api/v1/devices?site_id=ds_abc123&start=2026-03-01&end=2026-03-26&limit=10"

{
  "results": [
    { "device_type": "desktop", "visitors": 9000 },
    { "device_type": "mobile", "visitors": 2800 },
    { "device_type": "tablet", "visitors": 650 }
  ],
  "meta": {
    "site_id": "ds_abc123",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-26T23:59:59Z",
    "limit": 10
  }
}

Tip

All breakdown endpoints (pages, referrers, countries, browsers, etc.) support the same common parameters. Combine start, end, and limit to narrow down your query for faster responses.

Introduction

Visitors