Statsy API

The Statsy API is a REST-styled API that gives you access to the data exposed as HTTP endpoints.

API Basics

All endpoints live under the URL https://api.statsy.com.

Authentication

Access Tokens are required to authenticate and use the Statsy API.

Authorization: Bearer <TOKEN>

Creating an Access Token

Access Tokens can be created in the Statsy Dashboard (opens in a new tab).

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. If not otherwise specified, responses from the Statsy API, including errors, are encoded exclusively as JSON as well.

Track

POST/v2/beep

This endpoint allows you to track a visitor to your website. This endpoint should be called only on the server-side. It's useful if you want to track a visitor without having to load the Statsy JavaScript library.

Aggregate

GET/v2/stats/aggregate?domain={domain}

This endpoint returns aggregated statistical data for the specified domain. The aggregate data may include total counts, averages, or other summarized statistics about visitor data for the domain.

Breakdown

GET/v2/stats/breakdown?domain={domain}

This endpoint provides a detailed breakdown of statistics for a given domain. The breakdown can include specific data points like unique visits, returning visitors, page views, and more.

Realtime Visitors

GET/v2/stats/realtime?domain={domain}

This endpoint provides real-time data about current visitors on the domain.

Timeseries

GET/v2/stats/timeseries?domain={domain}

This endpoint returns statistical data over time for the specified domain. The data is returned in a format suitable for plotting on a time series graph, making it possible to visualize trends and patterns over time.

Top Stats

Top Pages

GET/v2/stats/top/pages?domain={domain}

Top Sources

GET/v2/stats/top/sources?domain={domain}

Get Carbon Footprint

GET/v1/carbon?url={url}

Get the carbon footprint of a given URL.

Query Parameters

Name	Type	Description
`url`	`string`	The URL to get the carbon footprint for.
`includeSubpages`	`boolean`	If set to `true`, response will include all subpages starting with the provided URL
`country`	`enum`	The Country Code to get the carbon footprint for, by default we try to guess it based on the origin request.

Example Request

await fetch("https://api.statsy.com/v1/carbon?url={url}", {
  "headers": {
    "Authorization": "Bearer <TOKEN>"
  },
})

Example Response

{
  "request": {
    "country": "US",
    "countryName": "United States of America",
    "emissionPerKwh": 378.625
  },
  "page": {
    "updatedAt": 1672964316963,
    "pathname": "/blog",
    "transferSize": 287.9,
    "emission": 0.082
  }
}

Calculate Carbon Footprint

By default, carbon footprint is cached for 24 hours, you can revalidate it by calling this endpoint.

POST/v1/carbon?url={url}

Query Parameters

Name	Type	Example	Description
`url`	`string`	`statsy.com/blog`	The URL to get the carbon footprint for.

Example Request

await fetch("https://api.statsy.com/v1/carbon?url={url}", {
  "method": "POST",
  "headers": {
    "Authorization": "Bearer <TOKEN>"
  },
})

Get Greencheck

GET/v1/greencheck?url={url}

Get the pagexray of a given URL.

Query Parameters

Name	Type	Example	Description
`url`	`string`	`dodonut.com`	The URL to get the carbon footprint for.

Example Request

await fetch("https://api.statsy.com/v1/greencheck?url={url}", {
  "headers": {
    "Authorization": "Bearer <TOKEN>"
  },
})

Example Response

{
  "green": true,
  "hosting": "Cloudflare"
}

Get Pagexray

GET/v1/pagexray?url={url}

Get the pagexray of a given URL.

Query Parameters

Name	Type	Example	Description
`url`	`string`	`statsy.com/blog`	The URL to get the carbon footprint for.

Example Request

Example Response

{
  "data": {
    "url": "https://statsy.com/blog",
    "meta": {
      "browser": {},
      "startedDateTime": "2022-12-15T18:11:04.086Z"
    },
    "finalUrl": "https://statsy.com/blog",
    "baseDomain": "statsy.com",
    "firstPartyRegEx": ".*statsy.*",
    "documentRedirects": 0,
    "redirectChain": [],
    "transferSize": 111391,
    "contentSize": 422139,
    "headerSize": 0,
    "requests": 13,
    "cookieNames": [],
    "cookieNamesThirdParties": [],
    "cookies": 0,
    "missingCompression": 10,
    "fullyLoaded": 1262.68994140625,
    "httpType": "h2",
    "httpVersion": "HTTP/2.0",
    "contentTypes": {
      "html": {
        "transferSize": 9071,
        "contentSize": 41771,
        "headerSize": 0,
        "requests": 1
      },
      "css": {
        "transferSize": 19530,
        "contentSize": 98873,
        "headerSize": 0,
        "requests": 5
      },
      "javascript": {
        "transferSize": 70363,
        "contentSize": 214872,
        "headerSize": 0,
        "requests": 3
      },
      "image": {
        "transferSize": 0,
        "contentSize": 0,
        "headerSize": 0,
        "requests": 0
      },
      "font": {
        "transferSize": 0,
        "contentSize": 0,
        "headerSize": 0,
        "requests": 0
      },
      "svg": {
        "transferSize": 12427,
        "contentSize": 66623,
        "headerSize": 0,
        "requests": 4
      }
    },
    "assets": [],
    "responseCodes": {
      "200": 13
    },
    "firstParty": {
      "cookies": 0,
      "contentTypes": {
        // ...
      },
      "requests": 9,
      "transferSize": 98964,
      "contentSize": 355516,
      "headerSize": -9
    },
    "thirdParty": {
      "cookies": 0,
      "contentTypes": {
        // ...
      },
      "requests": 4,
      "transferSize": 12427,
      "contentSize": 66623,
      "headerSize": -4
    },
    "domains": {
      "statsy.com": {
        "transferSize": 98964,
        "contentSize": 355516,
        "headerSize": -9,
        "requests": 9,
        "timings": {
          "blocked": 21,
          "dns": 23,
          "ssl": 86,
          "connect": 86,
          "send": 1,
          "wait": 2642,
          "receive": 14
        },
        "totalTime": 2873
      },
      "cdn.sanity.io": {
        // ...
      }
    },
    "expireStats": {
      "min": 0,
      "median": 31536000,
      "max": 31536000,
      "total": 378432000,
      "values": 13
    },
    "lastModifiedStats": {
      "min": 6489277,
      "median": 6489304,
      "max": 6510129,
      "total": 25978014,
      "values": 4
    },
    "afterOnContentLoad": {
      // ...
    },
    "afterOnLoad": {
      // ...
    },
    "totalDomains": 2
  }
}

Add Event

POST/v1/beep

💡

This endpoint should be only called from the backend. If you want to track users client-side, please use our tracking script. If you are using a custom domain, you can use it instead of api.statsy.com in the endpoint.

Request Headers

HTTP Header	Value	Required
`X-Forwarded-For`	Original IP of the user's request	Yes
`User-Agent`	User-Agent of the user's request	Yes
`Content-Type`	`application/json`	Yes

Body Parameters

The body of the request should be a JSON object with the following properties:

Parameter	Value	Required
`eventName`	The name of the event. By default it's `pageview`. Other event names will be considered a custom event (goal).	No (default to `pageview`)
`domain`	The ID of your Site. You can find it in the site settings.	Yes
`url`	Full URL of the user's request, including query params like utms	No
`label`	User-Agent of the user's request	No

Example request

await fetch("https://api.statsy.com/v1/beep", {
  "method": "POST",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.121 Safari/537.36 OPR/71.0.3770.284",
    "X-Forwarded-For": "127.0.0.1",
    "Content-Type": "application/json",
    "Authorization": "Bearer <TOKEN>"
  },
  "body": JSON.stringify({
    "name": "pageview",
    "url": "http://dummy.site",
    "domain": "dummy.site",
    "screen_width": 1666
  })
})

Example Response

{
  "status": "ok",
  "message": "Beeped!"
}

Track