GoatCounter

https://www.goatcounter.com/help/
Admin
GoatCounter is a privacy-focused web analytics platform that tracks visitor pageviews and events...
Tokens:18,889
Snippets:251
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Export Data via API

Source: https://www.goatcounter.com/help/api

This example demonstrates how to export data using the API. It starts an export, waits for completion, and then downloads the data. Error checking is omitted for brevity.

```shell
#!/bin/sh
token="[your api token]"
api="https://[my code].goatcounter.com/api/v0"
curl() {
    \command curl --silent \
        --header 'Content-Type: application/json' \
        --header "Authorization: Bearer $token" \
        "$@"
}

# Start a new export, get ID from response object.
id=$(curl -X POST "$api/export" | jq .id)

# The export is started in the background, so we'll need to wait until it's finished.
while :; do
    sleep 1

    finished=$(curl "$api/export/$id" | jq .finished_at)
    if [ "$finished" != "null" ]; then
        # Download the export.
        curl "$api/export/$id/download" | gzip -d

        break
    fi
done

```

--------------------------------

### Exporting Data to CSV

Source: https://www.goatcounter.com/help/api

Examples for exporting data via the API, including starting an export, checking its status, and downloading the results.

```APIDOC
## Exporting Data via API

This section details how to initiate, monitor, and download data exports using the GoatCounter API.

### POST /api/v0/export

#### Description
Starts a new data export process. The response contains an ID that can be used to track the export's progress and download the results.

#### Method
POST

#### Endpoint
/api/v0/export

#### Response
##### Success Response (200)
- **id** (string) - The unique identifier for the export job.

##### Response Example
```json
{
  "id": "export_job_id_123"
}
```

### GET /api/v0/export/{id}

#### Description
Retrieves the status of a data export job.

#### Method
GET

#### Endpoint
/api/v0/export/{id}

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the export job.

#### Response
##### Success Response (200)
- **finished_at** (string) - The timestamp when the export finished, or null if not yet finished.
- **error** (string) - An error message if the export failed.

##### Response Example
```json
{
  "finished_at": "2023-10-27T10:00:00Z",
  "error": null
}
```

### GET /api/v0/export/{id}/download

#### Description
Downloads the exported data. The data is typically gzipped.

#### Method
GET

#### Endpoint
/api/v0/export/{id}/download

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the export job.

#### Response
##### Success Response (200)
- The response contains the gzipped CSV data of the export.

##### Response Example
(Binary data, typically decompressed with gzip)

### Pagination
Exports can be synced regularly using the `last_hit_id` parameter, which acts as a cursor for pagination.
```

--------------------------------

### System Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the system_stats.jsonl format, showing daily operating system counts per path. The 'day' field is in YYYY-MM-DD format.

```json
{"day": "2019-08-15",  "path_id": 211,  "system_id": 9,   "count": 4}
{"day": "2019-08-15",  "path_id": 223,  "system_id": 52,  "count": 1}
{"day": "2019-08-15",  "path_id": 211,  "system_id": 48,  "count": 2}

```

--------------------------------

### Screen Size Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the size_stats.jsonl format, showing daily screen width counts per path. The 'day' field is in YYYY-MM-DD format.

```json
{"day": "2026-03-05",  "path_id": 211,      "width": 1280,  "count": 9}
{"day": "2026-03-07",  "path_id": 5990349,  "width": 1920,  "count": 4}
{"day": "2026-03-05",  "path_id": 5990350,  "width": 0,     "count": 1}

```

--------------------------------

### Browser Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the browser_stats.jsonl format, showing daily browser counts per path. The 'day' field is in YYYY-MM-DD format.

```json
{"day": "2019-08-15",  "path_id": 211,  "browser_id": 155,  "count": 1}
{"day": "2019-08-15",  "path_id": 223,  "browser_id": 92,   "count": 6}
{"day": "2019-08-15",  "path_id": 223,  "browser_id": 85,   "count": 1}

```

--------------------------------

### Start New Export with Cursor

Source: https://www.goatcounter.com/help/api

Initiates a new export process starting from a specified hit ID. The command uses curl to send a POST request with the start ID and jq to extract the new export ID.

```shell
id=$(curl -X POST "$api/export" --data "{\"start_from_hit_id\":$start}" | jq .id)
```

--------------------------------

### Get Overview of All Paths

Source: https://www.goatcounter.com/help/api

Retrieves an overview of all recorded paths.

```APIDOC
## GET /api/v0/paths

### Description
Get an overview of all paths.

### Method
GET

### Endpoint
/api/v0/paths
```

--------------------------------

### Language Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the language_stats.jsonl format, showing daily language counts per path. The 'day' field is in YYYY-MM-DD format.

```json
{"day": "2026-03-05",  "path_id": 211,  "language": "eng", "count": 1}
{"day": "2026-03-05",  "path_id": 211,  "language": "spa", "count": 2}
{"day": "2026-03-05",  "path_id": 211,  "language": "",    "count": 2}

```

--------------------------------

### Hit Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the hit_stats.jsonl format, showing hourly hit counts per path. The 'hour' field is in RFC3339 UTC format.

```json
{"hour": "2026-03-05T19:00:00Z",  "path_id": 211,       "ref_id": 1,         "count": 4}
{"hour": "2026-03-07T15:00:00Z",  "path_id": 5990349,   "ref_id": 30563812,  "count": 1}
{"hour": "2026-03-07T15:00:00Z",  "path_id": 82905422,  "ref_id": 30563812,  "count": 1}
{"hour": "2026-03-07T15:00:00Z",  "path_id": 5990349,   "ref_id": 30563813,  "count": 3}
{"hour": "2026-03-07T15:00:00Z",  "path_id": 82905422,  "ref_id": 30563814,  "count": 2}

```

--------------------------------

### Location Statistics JSONL Example

Source: https://www.goatcounter.com/help/export-json

Example of the location_stats.jsonl format, showing daily location counts per path. The 'location' field can be a country code or 'country-region'.

```json
{"day": "2026-03-05",  "path_id": 211,  "location": "IN",     "count": 1}
{"day": "2026-03-05",  "path_id": 211,  "location": "RO-B",   "count": 1}
{"day": "2026-03-05",  "path_id": 211,  "location": "IT-82",  "count": 1}
{"day": "2026-03-07",  "path_id": 350,  "location": "",       "count": 4}

```

--------------------------------

### JSON Lines Format Example

Source: https://www.goatcounter.com/help/export-json

Demonstrates the JSON Lines format where each line is a valid JSON object. This format is used for files like languages.jsonl, locations.jsonl, paths.jsonl, refs.jsonl, browsers.jsonl, and systems.jsonl.

```json
{"key": "value"}
{"key": "value"}
{"key": "value"}
```

--------------------------------

### Get Stats for Browser, System, etc.

Source: https://www.goatcounter.com/help/api

Retrieves statistics related to browsers, systems, and other categories.

```APIDOC
## GET /api/v0/stats/{page}

### Description
Get stats for browser, system, etc.

### Method
GET

### Endpoint
/api/v0/stats/{page}
```

--------------------------------

### paths.jsonl List of Paths and Events

Source: https://www.goatcounter.com/help/export-json

Lists all tracked paths and events. Paths start with '/', while events do not. The 'event' field is present for events and omitted for regular paths.

```json
{"id": 211,                    "path": "/",            "title": "Home page"}
{"id": 215,                    "path": "/api",         "title": "API Documentation"}
{"id": 1442298, "event": true, "path": "click-banana", "title": "Yellow curvy fruit"}
```

--------------------------------

### Get Query Parameter and Set Referrer

Source: https://www.goatcounter.com/help/js

This script configures `window.goatcounter.referrer` to retrieve a query parameter (e.g., 'ref') or fall back to `document.referrer`. It also includes the GoatCounter script tag.

```javascript
<script>
    window.goatcounter = {
        referrer: function() {
            return goatcounter.get_query('ref') ||
                goatcounter.get_query('utm_campaign') ||
                goatcounter.get_query('utm_source') ||
                document.referrer
        },
    }
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Get Current User Information

Source: https://www.goatcounter.com/help/api

Retrieves information about the currently authenticated user.

```APIDOC
## GET /api/v0/me

### Description
Get information about the current user.

### Method
GET

### Endpoint
/api/v0/me
```

--------------------------------

### Get Last Hit ID for Export

Source: https://www.goatcounter.com/help/api

Retrieves the last hit ID from an existing export using curl and jq. This ID can be used to start a new export from a specific point.

```shell
start=$(curl "$api/export/$id" | jq .last_hit_id)
```

--------------------------------

### Get View/Visitor Statistics per Path

Source: https://www.goatcounter.com/help/api

Retrieves view and visitor statistics broken down by path.

```APIDOC
## GET /api/v0/stats/hits

### Description
Get view/visitor statistics per path.

### Method
GET

### Endpoint
/api/v0/stats/hits
```

--------------------------------

### Get Current User Information

Source: https://www.goatcounter.com/help/api

Retrieves information about the currently authenticated user. This is a basic endpoint to verify API key validity and permissions.

```APIDOC
## GET /api/v0/me

### Description
Retrieves information about the currently authenticated user.

### Method
GET

### Endpoint
/api/v0/me

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://example.goatcounter.com/api/v0/me \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer [YOUR_API_KEY]' \
```

### Response
#### Success Response (200)
- **user** (object) - User details.
- **sites** (array) - List of sites associated with the user.

#### Response Example
```json
{
  "user": {
    "email": "user@example.com",
    "name": "User Name"
  },
  "sites": [
    {
      "id": "site123",
      "name": "Example Site"
    }
  ]
}
```
```

--------------------------------

### Implement Do Not Track in GoatCounter Script

Source: https://www.goatcounter.com/help/faq

Add this script to the start of your GoatCounter implementation to respect the Do Not Track header. This is useful if you want to honor user privacy preferences.

```javascript
<script>
window.goatcounter = {
    no_onload: (‘doNotTrack’ in navigator && navigator.doNotTrack === ‘1’),
};
</script>
<script data-goatcounter=“[..]”
    async src=“//gc.zgo.at/count.js”></script>
```

--------------------------------

### Allow embedding in an iframe

Source: https://www.goatcounter.com/help/frame

Add domains or URLs to the 'Sites that can embed GoatCounter' setting to permit iframe embedding. This example shows a basic domain.

```html
<iframe src="https://MYCODE.goatcounter.com?access-token=TOKEN"></iframe>
```

--------------------------------

### Get Referral Stats for a Path

Source: https://www.goatcounter.com/help/api

Retrieves referral statistics for a specific path.

```APIDOC
## GET /api/v0/stats/hits/{path_id}

### Description
Get referral stats for a path.

### Method
GET

### Endpoint
/api/v0/stats/hits/{path_id}
```

--------------------------------

### Dynamically Set JavaScript Endpoint

Source: https://www.goatcounter.com/help/modify

This example demonstrates how to set the GoatCounter endpoint dynamically in JavaScript based on the current hostname. This is useful for sending data to different sites. Ensure this script runs before count.js is loaded or call window.goatcounter.count() manually.

```html
<script>
    var code = '';
    switch (location.hostname) {
    case 'example.com':
        code = 'a'
        break
    case 'example.org':
        code = 'b'
        break
    default:
        code = 'c'
    }
    window.goatcounter = {
        endpoint: 'https://' + code + '.goatcounter.com/count',
    }
</script>
<script async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Prevent Tracking with JavaScript (Path Matching)

Source: https://www.goatcounter.com/help/skip-path

Configure JavaScript to conditionally set `window.goatcounter.no_onload` based on the current URL path. This example skips tracking for specific paths or patterns.

```javascript
['/wp-admin.php', '^/feed/.*'].forEach((p) => {
    if (p === window.location.pathname || window.location.pathname.match(p))
        window.goatcounter = {no_onload: true}
})

```

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>

```

--------------------------------

### Get Export Information

Source: https://www.goatcounter.com/help/api

Retrieves information about a specific CSV export.

```APIDOC
## GET /api/v0/export/{id}

### Description
Get information about a CSV export.

### Method
GET

### Endpoint
/api/v0/export/{id}
```

--------------------------------

### Error Reporting with 'error' field

Source: https://www.goatcounter.com/help/api

An example of an error response using the 'error' field, which contains a single string message. This format is used for simple error cases.

```json
{
    "error": "oh noes!"
}
```

--------------------------------

### Prevent Tracking with JavaScript (Body Class)

Source: https://www.goatcounter.com/help/skip-path

Set `window.goatcounter.no_onload` in JavaScript before the main script loads. This example skips tracking if the body class contains 'goatcounter-skip'.

```javascript
window.goatcounter = {
    no_onload: body.classList.contains('goatcounter-skip'),
}

```

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>

```

--------------------------------

### Error Reporting with 'errors' field

Source: https://www.goatcounter.com/help/api

An example of an error response using the 'errors' field, which contains a structured object with keys mapping to lists of error strings. This is used for more complex error scenarios.

```json
{
    "errors": {
        "key":     ["error1", "error2"],
        "another": ["oh noes!"]
    }
}
```

--------------------------------

### Fetch Visitor Count via JSON

Source: https://www.goatcounter.com/help/visitor-counter

Use this JavaScript code to fetch visitor count data as JSON and display it in a designated HTML element. It utilizes XMLHttpRequest to make a GET request to the GoatCounter JSON endpoint.

```javascript
<div>Number of visitors: <div id="stats"></div></div>

<script>
    let r = new XMLHttpRequest();
    r.addEventListener('load', function() {
        document.querySelector('#stats').innerText = JSON.parse(this.responseText).count
    })

    // Should be exact (encoded) path as it appears in the UI. This uses
    // GoatCounter's count.js
    let path = window.goatcounter.get_data()['p']

    // Or alternatively, do it manually. Will return HTTP status 404 if the
    // path is not found).
    //let path = location.pathname

    r.open('GET', 'https://MYCODE.goatcounter.com/counter/' + encodeURIComponent(path) + '.json')
    r.send()
</script>
```

--------------------------------

### systems.jsonl List of Operating Systems

Source: https://www.goatcounter.com/help/export-json

Provides a list of all operating systems, including their name and version. Version information may be blank.

```json
{"id": 2,   "name": "Android",  "version": "7.1"}
{"id": 3,   "name": "Linux",    "version": "Ubuntu"}
{"id": 18,  "name": "Windows",  "version": "10"}
{"id": 39,  "name": "",         "version": ""}
```

--------------------------------

### Create New Site

Source: https://www.goatcounter.com/help/api

Creates a new site.

```APIDOC
## PUT /api/v0/sites

### Description
Create a new site.

### Method
PUT

### Endpoint
/api/v0/sites
```

--------------------------------

### Import Logfile Data with GoatCounter

Source: https://www.goatcounter.com/help/logfile

Use this command to import Nginx access log data. The `-follow` flag keeps watching the file for new entries, while `-format=combined` specifies the log format. Replace `MYCODE` with your actual GoatCounter site code. Ensure the `GOATCOUNTER_API_KEY` environment variable is set.

```bash
$ export GOATCOUNTER_API_KEY=[..]
$ goatcounter import -follow -format=combined -exclude=static \
  -site='https://MYCODE.goatcounter.com' \
  /var/log/nginx/access_log

```

--------------------------------

### Create Table and Import CSV in PostgreSQL

Source: https://www.goatcounter.com/help/export

Provides SQL commands to create a table schema matching the CSV export structure and then import the CSV data into that table in PostgreSQL. The 'header on' option ensures the first line of the CSV is used as column names.

```postgresql
=# create table gc_export (
    "2Path"             varchar,
    "Title"             varchar,
    "Event"             varchar,
    "UserAgent"         varchar,
    "Browser"           varchar,
    "System"            varchar,
    "Session"           varchar,
    "Bot"               varchar,
    "Referrer"          varchar,
    "Referrer scheme"   varchar,
    "Screen size"       varchar,
    "Location"          varchar,
    "FirstVisit"        varchar,
    "Date"              varchar
);

=# \copy gc_export from 'gc_export.csv' with (format csv, header on);
```

--------------------------------

### Set Up Custom Domain with CNAME Record

Source: https://www.goatcounter.com/help/faq

Configure a CNAME record in your DNS settings to point to your GoatCounter subdomain. This allows you to use a custom domain for your stats. Note that this may take a few hours to propagate.

```dns
stats   IN CNAME    mine.goatcounter.com.
```

--------------------------------

### Set Path with data-goatcounter-settings

Source: https://www.goatcounter.com/help/path

Configure the path sent to GoatCounter using the `data-goatcounter-settings` attribute on the script tag. This attribute expects valid JSON.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        data-goatcounter-settings='{"path": "/hello"}'
        async src="//zgo.at/count.js"></script>

```

--------------------------------

### Configure GoatCounter with window.goatcounter

Source: https://www.goatcounter.com/help/js

Set `window.goatcounter` properties before loading the `count.js` script to configure GoatCounter. This is an alternative to using the `data-goatcounter-settings` attribute.

```javascript
window.goatcounter = {allow_local: true}

```

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>

```

--------------------------------

### Set Fixed Path using window.goatcounter object

Source: https://www.goatcounter.com/help/js

Configure a fixed path by setting the `path` property on the `window.goatcounter` object before loading the tracking script. This method is useful for dynamic configurations.

```javascript
window.goatcounter = {path: '/hello'}

```

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>

```

--------------------------------

### Configure GoatCounter with data-goatcounter-settings

Source: https://www.goatcounter.com/help/js

Use the `data-goatcounter-settings` attribute on the script tag to configure GoatCounter. Ensure the value is valid JSON. This method overrides any existing `window.goatcounter` settings.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        data-goatcounter-settings='{"allow_local": true}'
        async src="//static.goatcounter.localhost:8081/count.js"></script>

```

--------------------------------

### browsers.jsonl List of Browsers

Source: https://www.goatcounter.com/help/export-json

Lists all identified browsers, including their name and version. The version is typically numeric but should not be relied upon as such.

```json
{"id": 1,   "name": "Chrome",   "version": "46"}
{"id": 29,  "name": "",         "version": ""}
{"id": 37,  "name": "Firefox",  "version": "83"}
```

--------------------------------

### List Sites

Source: https://www.goatcounter.com/help/api

Retrieves a list of all sites associated with the account.

```APIDOC
## GET /api/v0/sites

### Description
List sites.

### Method
GET

### Endpoint
/api/v0/sites
```

--------------------------------

### Include count.js with goatcounter.endpoint configuration

Source: https://www.goatcounter.com/help/countjs-host

Alternatively, include the count.js script and configure the GoatCounter endpoint by setting the window.goatcounter.endpoint variable before the script's content is loaded.

```javascript
<script>
    window.goatcounter = {endpoint: 'https://MYCODE.goatcounter.com/count'}

    // [.. contents of count.js ..]
</script>
```

--------------------------------

### Import CSV into SQLite and Query

Source: https://www.goatcounter.com/help/export

Demonstrates how to import a CSV export into an SQLite database and perform a basic query to count pageviews by location. Ensure the CSV file is named 'gc_export.csv'.

```sqlite
sqlite> .import --csv gc_export.csv gc_export
sqlite> select
   ...>   count(*) as count,
   ...>   substr(Location, 0, 3) as location
   ...> from gc_export
   ...> where location != ''
   ...> group by location
   ...> order by count desc
   ...> limit 20;
```

--------------------------------

### Load Tracking Pixel Directly

Source: https://www.goatcounter.com/help/pixel

Embed this HTML to load the tracking pixel directly. Replace MYCODE with your GoatCounter code.

```html
<img src="https://MYCODE.goatcounter.com/count?p=/test">

```

--------------------------------

### Create CSV Export

Source: https://www.goatcounter.com/help/api

Initiates a new CSV export.

```APIDOC
## POST /api/v0/export

### Description
Create a new CSV export.

### Method
POST

### Endpoint
/api/v0/export
```

--------------------------------

### Use Tracking Pixel with CSS

Source: https://www.goatcounter.com/help/pixel

Apply the tracking pixel as a CSS background image. Replace MYCODE with your GoatCounter code.

```css
<style>
body:hover {
    border-image: url("https://MYCODE.goatcounter.com/count?p=/test");
}
</style>

```

--------------------------------

### Advanced GoatCounter Integration via JavaScript

Source: https://www.goatcounter.com/help

Use this JavaScript snippet for more control over the script loading and initialization. It dynamically creates and appends the script tag to the document body, allowing for deferred execution.

```javascript
const script = document.createElement('script');
script.setAttribute('defer', true);
script.setAttribute('src', 'https://gc.zgo.at/count.js');
script.setAttribute('data-goatcounter', 'https://MYCODE.goatcounter.com/count');
document.body.appendChild(script);
```

--------------------------------

### Conditionally Load GoatCounter with JavaScript

Source: https://www.goatcounter.com/help/skip-dev

Use this JavaScript snippet to ensure GoatCounter only loads on your production domain (`production.com`) and not on staging or development environments. Set `window.goatcounter = {no_onload: true}` before the main script to prevent loading.

```javascript
<script>
    // Only load on production environment.
    if (window.location.host !== 'production.com')
        window.goatcounter = {no_onload: true}
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Basic CSP Directives for GoatCounter

Source: https://www.goatcounter.com/help/csp

Add these directives to your Content-Security-Policy header to allow GoatCounter's script to load and send data. The `script-src` directive permits loading `count.js` from the specified domain, and `connect-src` allows sending pageviews using `navigator.sendBeacon`.

```http
script-src  https://gc.zgo.at
connect-src https://MYCODE.goatcounter.com/count
```

--------------------------------

### Session Tracking Logic

Source: https://www.goatcounter.com/help/sessions

This pseudo-code outlines the logic for identifying and counting visits. It checks for existing sessions, determines if a new visit should be counted based on the path, and generates new sessions when necessary. Only a random UUID is stored, not the session key.

```pseudo-code
session_key    = site_id + user_agent + IP
count_as_visit = false

# We've seen this session before.
if sessions[session_key] and sessions[session_key].newer_than(8_hours)
    # Only count as visit if this session hasn't visited this path yet.
    if not sessions[session_key].seen_path(current_path)
        count_as_visit = true
        add_current_path(sessions[session_key])
    end
else
    # Generate new session.
    sessions[session_key] = create_random_uuid()
    add_current_path(sessions[session_key])
    count_as_visit = true
end

# Store pageview; only the random UUID in sessions[session_key] is stored,
# and NOT session_key
store_pageview()

# Increate counter to make the charts go up.
if count_as_visit
    increase_counter_in_database()
end

```

--------------------------------

### languages.jsonl List of Languages

Source: https://www.goatcounter.com/help/export-json

Lists all supported languages, including their ISO 639-3 code and name. The 'iso_639_3' field can be empty for unknown languages.

```json
{"iso_639_3": "",    "name": "(unknown)"}
{"iso_639_3": "aaa", "name": "Ghotuo"}
{"iso_639_3": "aao", "name": "Algerian Saharan Arabic"}
```

--------------------------------

### Basic GoatCounter Integration

Source: https://www.goatcounter.com/help

Add this script tag to your HTML to enable basic pageview tracking. Ensure the `data-goatcounter` attribute points to your unique GoatCounter endpoint. This script should be placed anywhere on the page.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Direct URL Counter Path

Source: https://www.goatcounter.com/help/visitor-counter

Construct direct URLs to fetch visitor counts as HTML, PNG, SVG, or JSON. Replace MYCODE with your GoatCounter code and specify the path and extension.

```plaintext
https://MYCODE.goatcounter.com/counter/[PATH].[EXT]
```

--------------------------------

### url(vars)

Source: https://www.goatcounter.com/help/js

Generates the URL to send to the server for tracking. The `vars` parameter behaves the same as in the `count()` method.

```APIDOC
## url(vars)

### Description
Get URL to send to the server; the `vars` parameter behaves as `count()`.
Note that you may want to use `filter()` to exclude prerender requests and various other things.

### Parameters
#### Request Body
- **vars** (object) - An object containing data parameters to construct the URL.
```

--------------------------------

### Wait for GoatCounter to Load

Source: https://www.goatcounter.com/help/js

Use this interval to ensure `window.goatcounter` and its `count` method are available before attempting to use them. Remove `async` from the script tag or use this callback.

```javascript
var t = setInterval(function() {
    if (!window.goatcounter || !window.goatcounter.count)
        return

    clearInterval(t)
    // Do stuff with goatcounter here.
}, 100)
```

--------------------------------

### Detailed Stats (e.g. browser version)

Source: https://www.goatcounter.com/help/api

Retrieves detailed statistics, such as browser versions.

```APIDOC
## GET /api/v0/stats/{page}/{id}

### Description
Detailed stats (e.g. browser version).

### Method
GET

### Endpoint
/api/v0/stats/{page}/{id}
```

--------------------------------

### Custom Path and Referrer Logic

Source: https://www.goatcounter.com/help/modify

Use this snippet to implement custom logic for the 'path' parameter, such as excluding specific pages or cleaning up URL formats. Ensure the script is placed before the main count.js script.

```html
<script>
    window.goatcounter = {
        // The passed value is the default.
        path: function(p) {
            // Don't track the home page.
            if (p === '/')
                return null

            // Remove .html from all other page links.
            return p.replace(/\.html$/, '')
        },
    }
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### JavaScript Integration with Noscript Fallback

Source: https://www.goatcounter.com/help/pixel

Use this script for JavaScript-enabled users and the noscript tag for those without JavaScript. Ensure the 'data-goatcounter' attribute points to your GoatCounter endpoint and update '/INSERT-PAGE-HERE' with the correct page path.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
<noscript>
    <img src="https://MYCODE.goatcounter.com/count?p=/INSERT-PAGE-HERE">
</noscript>

```

--------------------------------

### Update Site

Source: https://www.goatcounter.com/help/api

Updates an existing site.

```APIDOC
## POST /api/v0/sites/{id}

### Description
Update a site.

### Method
POST

### Endpoint
/api/v0/sites/{id}
```

--------------------------------

### Append Domain to Path for Multi-Domain Tracking

Source: https://www.goatcounter.com/help/domains

Configure GoatCounter to include the host domain in the recorded path. This is useful for distinguishing requests from different subdomains within a single site overview. Ensure the script is loaded before the main GoatCounter script.

```javascript
window.goatcounter = {
    path: function(p) { return location.host + p }
}
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Authenticate API Request with cURL

Source: https://www.goatcounter.com/help/api

Use this cURL command to authenticate your API requests by including your API key in the Authorization header. Replace the placeholder URL and key with your actual values.

```bash
curl https://example.goatcounter.com/api/v0/me \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 2q2snk7clgqs63tr4xc5bwseajlw88qzilr8fq157jz3qxwwmz5'
```

--------------------------------

### Understand API Rate Limit Headers

Source: https://www.goatcounter.com/help/api

These response headers provide information about the current API rate limit status. They indicate the total limit, remaining requests, and when the limit will reset.

```text
X-Rate-Limit-Limit        Number of requests the rate limit kicks in; this is always the same.
X-Rate-Limit-Remaining    Requests remaining this period.
X-Rate-Limit-Reset        Seconds until the rate limits resets.
```

--------------------------------

### Query Hit Statistics

Source: https://www.goatcounter.com/help/export-json

SQL query to aggregate hit counts by hour and path_id. Ensure data is sorted by date for correct import.

```sql
select path_id, hour, sum(count) from hit_stats
group by hour, path_id
order by hour

```

--------------------------------

### Count Pageviews

Source: https://www.goatcounter.com/help/api

Endpoint to record pageviews.

```APIDOC
## POST /api/v0/count

### Description
Count pageviews.

### Method
POST

### Endpoint
/api/v0/count
```

--------------------------------

### Set Custom Path with window.goatcounter

Source: https://www.goatcounter.com/help/path

Override the path sent to GoatCounter by setting the `window.goatcounter` object before the `count.js` script loads. This allows for dynamic path generation.

```javascript
window.goatcounter = {
    path: location.pathname || '/',
}

```

```javascript
window.goatcounter = {
    path: function() {
        return location.pathname + '?page=' + (goatcounter.get_query('page')) || '/'),
    },
}

```

--------------------------------

### Detailed Site Information

Source: https://www.goatcounter.com/help/api

Retrieves detailed information about a specific site.

```APIDOC
## GET /api/v0/sites/{id}

### Description
Detailed information about a site.

### Method
GET

### Endpoint
/api/v0/sites/{id}
```

--------------------------------

### refs.jsonl List of Referrers

Source: https://www.goatcounter.com/help/export-json

Contains a list of all referrers, categorized by scheme (HTTP, generated, campaign, other). Referenced in hit statistics.

```json
{"id": 1,        "ref": "",                       "ref_scheme": "o"}
{"id": 69853,    "ref": "Google",                 "ref_scheme": "g"}
{"id": 2176502,  "ref": "example.com/page.html",  "ref_scheme": "h"}
```

--------------------------------

### Set Canonical URL for Path

Source: https://www.goatcounter.com/help/path

Use a canonical URL in the `<head>` to ensure a consistent path is sent to GoatCounter. The `href` can be absolute or relative.

```html
<link rel="canonical" href="https://example.com/path">

```

```html
<link rel="canonical" href="https://my-other-site.com/path">

```

--------------------------------

### Partially Update Site

Source: https://www.goatcounter.com/help/api

Partially updates an existing site.

```APIDOC
## PATCH /api/v0/sites/{id}

### Description
Update a site.

### Method
PATCH

### Endpoint
/api/v0/sites/{id}
```

--------------------------------

### Dynamic Event Path from JavaScript

Source: https://www.goatcounter.com/help/events

Dynamically set the event path in JavaScript using a function within the `goatcounter.count()` call. This allows for more complex event naming based on context.

```javascript
window.goatcounter.count({
    path:  function(p) { return 'click-banana-' + p },
    event: true,
})
```

--------------------------------

### Integrate count.js v1 with SRI

Source: https://www.goatcounter.com/help/countjs-versions

Use this snippet to include version 1 of count.js with Subresource Integrity (SRI) enabled. This ensures the script's integrity and prevents unauthorized modifications.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
      async src="//gc.zgo.at/count.v1.js"
      crossorigin="anonymous"
      integrity="sha384-RD/1OXO6tEoPGqxhwMKSsVlE5Y1g/pv/Pf2ZOcsIONjNf1O+HPABMM4MmHd3l5x4"></script>
```

--------------------------------

### JavaScript Integration for Visitor Count

Source: https://www.goatcounter.com/help/visitor-counter

Appends the visitor count to the body of the HTML document. Ensure the count.js script is loaded before calling visit_count.

```html
<script>
    // Append to the <body>; can use a CSS selector to append somewhere else.
    window.goatcounter.visit_count({append: 'body'})
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

```html
<script>
    var t = setInterval(function() {
        if (window.goatcounter && window.goatcounter.visit_count) {
            clearInterval(t)
            window.goatcounter.visit_count({append: 'body'})
        }
    }, 100)
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### Content Security Policy Directive

Source: https://www.goatcounter.com/help/pixel

Add this directive to your Content Security Policy to allow the tracking pixel image to load.

```http
img-src https://MYCODE.goatcounter.com/count

```

--------------------------------

### Embed with access token and hidden UI

Source: https://www.goatcounter.com/help/frame

Combine `access-token` and `hideui=1` in the iframe src URL to authenticate and simplify the embedded view.

```html
<iframe src="https://MYCODE.goatcounter.com?access-token=TOKEN&hideui=1"></iframe>
```

--------------------------------

### SPA Custom Count with Hash Navigation

Source: https://www.goatcounter.com/help/spa

Use this snippet to track page views in an SPA that uses hash-based routing. It listens for hash changes and manually calls the GoatCounter `count()` function.

```html
<script>
    window.goatcounter = {no_onload: true}

    window.addEventListener('hashchange', function(e) {
        window.goatcounter.count({
            path: location.pathname + location.search + location.hash,
        })
    })
</script>
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.js"></script>
```

--------------------------------

### List Total Pageview Counts

Source: https://www.goatcounter.com/help/api

Retrieves the total pageview counts.

```APIDOC
## GET /api/v0/stats/total

### Description
List total pageview counts.

### Method
GET

### Endpoint
/api/v0/stats/total
```

--------------------------------

### Include count.js with data-goatcounter attribute

Source: https://www.goatcounter.com/help/countjs-host

Use this method to include the count.js script directly in your HTML body and specify the GoatCounter endpoint using the data-goatcounter attribute.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count">
    // [.. contents of count.js ..]
</script>
```

--------------------------------

### Send Pageviews from Backend with Curl

Source: https://www.goatcounter.com/help/backend

Use this curl command to send pageview data to the GoatCounter API from your application's backend or other sources. Ensure you replace '[your api token]' and 'MYCODE' with your actual token and GoatCounter domain.

```bash
token=[your api token]
api=https://MYCODE.goatcounter.com/api/v0

curl -X POST "$api/count" \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $token" \
    --data '{"no_sessions": true, "hits": [{"path": "/one"}, {"path": "/two"}]}'
```

--------------------------------

### Sending Pageviews from a Backend

Source: https://www.goatcounter.com/help/api

Use the /api/v0/count endpoint to send pageviews from your backend. This endpoint supports higher rate-limits, additional fields, and batching multiple pageviews in a single request.

```APIDOC
## POST /api/v0/count

### Description
Sends pageviews to GoatCounter from a backend application. This endpoint is similar to the JavaScript integration's `/count` but offers higher rate limits and more flexibility.

### Method
POST

### Endpoint
/api/v0/count

### Request Body
- **no_sessions** (boolean) - Optional - If true, disables session tracking for these hits.
- **hits** (array) - Required - An array of hit objects to record.
  - **path** (string) - Required - The path of the page visited.
  - **referrer** (string) - Optional - The referrer URL.
  - **user_agent** (string) - Optional - The user agent string.
  - **ip** (string) - Optional - The IP address of the visitor.
  - **timestamp** (integer) - Optional - The Unix timestamp of the hit.

### Request Example
```json
{
  "no_sessions": true,
  "hits": [
    {"path": "/one"},
    {"path": "/two"}
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "OK"
}
```
```

--------------------------------

### Integrate count.js v5 with SRI

Source: https://www.goatcounter.com/help/countjs-versions

Use this snippet to include version 5 of count.js with Subresource Integrity (SRI) enabled. This ensures the script's integrity and prevents unauthorized modifications.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.v5.js"
        crossorigin="anonymous"
        integrity="sha384-atnOLvQb9t+jTSipvd75X2yginT4PjVbqDdlJAmxMm+wYElFmeR6EmLP5bYeoRVQ"></script>
```

--------------------------------

### Integrate count.js v2 with SRI

Source: https://www.goatcounter.com/help/countjs-versions

Use this snippet to include version 2 of count.js with Subresource Integrity (SRI) enabled. This ensures the script's integrity and prevents unauthorized modifications.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.v2.js"
        crossorigin="anonymous"
        integrity="sha384-PeYXrhTyEaBBz91ANMgpSbfN1kjioQNPHNDbMvevUVLJoWrVEjDCpKb71TehNAlj"></script>
```

--------------------------------

### Sending Events from JavaScript

Source: https://www.goatcounter.com/help/events

Send a custom event from JavaScript by setting the `event` parameter to `true` in the `goatcounter.count()` function. The `path` parameter serves as the event name.

```javascript
$('#banana').on('click', function(e) {
    window.goatcounter.count({
        path:  'click-banana',
        title: 'Yellow curvy fruit',
        event: true,
    })
})
```

--------------------------------

### count(vars)

Source: https://www.goatcounter.com/help/js

Sends a pageview or event to GoatCounter. The `vars` parameter is an object that will be merged with the global `window.goatcounter` object.

```APIDOC
## count(vars)

### Description
Send a pageview or event to GoatCounter; the `vars` parameter is an object as described in the _Data parameters_ section above, and will be merged in to the global `window.goatcounter`, if it exists.

### Parameters
#### Request Body
- **vars** (object) - An object containing data parameters to be sent with the event or pageview.
```

--------------------------------

### info.json Export Metadata

Source: https://www.goatcounter.com/help/export-json

Contains metadata about the export, including the export version, GoatCounter version, and creation details. The goatcounter_version may be a commit hash for non-tagged releases.

```json
{
    "export_version":      "1.0",
    "goatcounter_version": "2.7",
    "created_for":         "stats.arp242.net",
    "created_by":          "user_id=1 <martin@arp242.net>",
    "created_at":          "2026-03-07T16:49:27Z"
}
```

--------------------------------

### filter()

Source: https://www.goatcounter.com/help/js

Determines if the current request should be filtered, returning a string with the reason or `false` if it should not be filtered. This helps filter bots, pre-render requests, frames, and local requests.

```APIDOC
## filter()

### Description
Determine if this request should be filtered; this returns a string with the reason or `false`.
This will filter some bots, pre-render requests, frames (unless `allow_frame` is set), and local requests (unless `allow_local` is set).

### Response
- **string** - The reason for filtering if the request is filtered.
- **false** - If the request should not be filtered.
```

--------------------------------

### Send Pageviews via API

Source: https://www.goatcounter.com/help/api

Use the /api/v0/count endpoint to send pageviews from your backend. This method offers higher rate limits and allows for batching multiple pageviews in a single request.

```shell
#!/bin/sh
token="[your api token]"
api="https://[my code].goatcounter.com/api/v0"
curl() {
    \command curl --silent \
        --header 'Content-Type: application/json' \
        --header "Authorization: Bearer $token" \
        "$@"
}

curl -X POST  "$api/count" \
    --data '{"no_sessions": true, "hits": [{"path": "/one"}, {"path": "/two"}]}'

```

--------------------------------

### Block Own Visits via URL Hash

Source: https://www.goatcounter.com/help/skip-dev

Append `#toggle-goatcounter` to your site's URL to prevent tracking your browser's pageviews. Reload the page (F5) after adding it to your URL bar for the effect to take hold.

```html
https://example.com#toggle-goatcounter
```

--------------------------------

### bind_events()

Source: https://www.goatcounter.com/help/js

Binds a click event to all elements with the `data-goatcounter-click` attribute. This is called on page load by default, but can be called manually if elements are added dynamically.

```APIDOC
## bind_events()

### Description
Bind a click event to every element with `data-goatcounter-click`. Called on page load unless `no_onload` or `no_events` is set. You may need to call this manually if you insert elements after the page loads.
See Events for more details about events.
```

--------------------------------

### Integrate count.js v3 with SRI

Source: https://www.goatcounter.com/help/countjs-versions

Use this snippet to include version 3 of count.js with Subresource Integrity (SRI) enabled. This ensures the script's integrity and prevents unauthorized modifications.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.v3.js"
        crossorigin="anonymous"
        integrity="sha384-QGgNMMRFTi8ul5kHJ+vXysPe8gySvSA/Y3rpXZiRLzKPIw8CWY+a3ObKmQsyDr+a"></script>
```

--------------------------------

### Download CSV Export

Source: https://www.goatcounter.com/help/api

Downloads a generated CSV export.

```APIDOC
## GET /api/v0/export/{id}/download

### Description
Download CSV export.

### Method
GET

### Endpoint
/api/v0/export/{id}/download
```

--------------------------------

### Integrate count.js v4 with SRI

Source: https://www.goatcounter.com/help/countjs-versions

Use this snippet to include version 4 of count.js with Subresource Integrity (SRI) enabled. This ensures the script's integrity and prevents unauthorized modifications.

```html
<script data-goatcounter="https://MYCODE.goatcounter.com/count"
        async src="//gc.zgo.at/count.v4.js"
        crossorigin="anonymous"
        integrity="sha384-nRw6qfbWyJha9LhsOtSb2YJDyZdKvvCFh0fJYlkquSFjUxp9FVNugbfy8q1jdxI+"></script>
```

--------------------------------

### Filter Bot and Prerender Requests

Source: https://www.goatcounter.com/help/js

Call `goatcounter.filter()` to determine if the current request should be filtered. This helps exclude bots, prerender requests, and frames. Log a warning if a filter is applied.

```javascript
var f = goatcounter.filter()
if (f) {
    if (console && 'log' in console)
        console.warn('goatcounter: not counting because of: ' + f)
    return
}
```

--------------------------------

### Automatic Click Event Tracking

Source: https://www.goatcounter.com/help/events

Bind a click event to any element with the `data-goatcounter-click` attribute to track external link clicks. The attribute value is used as the event name.

```html
<a href="https://example.com" data-goatcounter-click="ext-example.com">Example</a>
```
Tokens:
Raw