POST /api/v0/count
Count pageviews.
§
This can count one or more pageviews. Pageviews are not persisted immediately, but persisted in the background every 10 seconds.
The maximum amount of pageviews per request is 500.
Errors will have the key set to the index of the pageview. Any pageviews not listed have been processed and shouldn't be sent again.
202 Accepted
202 Accepted (no data)
(application/json)400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/export/{id}
Get details about an export.
§
200 OK
v2.Export
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/export/{id}/download
Download an export file.
§
The export may take a while to generate, depending on the size. It will return a 202 Accepted status code if the export ID is still running.
Export files are kept for 24 hours, after which they're deleted. This will return a 400 Gone status code if the export has been deleted.
200 OK
200 OK (text/csv data)
(text/csv)202 Accepted
handlers.apiError
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
POST /api/v0/export
Start a new export in the background.
§
This starts a new export in the background; this can only be done once an hour.
202 Accepted
v2.Export
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/paths
Get an overview of paths on this site (without statistics).
§
200 OK
handlers.apiPathsResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/sites
List all sites.
§
200 OK
handlers.apiSitesResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/sites/{id}
Get information about a site.
§
Get all information about one site.
200 OK
goatcounter.Site
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
PATCH /api/v0/sites/{id}
Update a site.
§
A POST request will *replace* the entire site with what's sent, blanking out any existing fields that may exist. A PATCH request will only update the fields that are sent.
200 OK
goatcounter.Site
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
POST /api/v0/sites/{id}
Update a site.
§
A POST request will *replace* the entire site with what's sent, blanking out any existing fields that may exist. A PATCH request will only update the fields that are sent.
200 OK
goatcounter.Site
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
PUT /api/v0/sites
Create a new site.
§
200 OK
goatcounter.Site
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/stats/hits
Get an overview of pageviews.
§
200 OK
handlers.apiHitsResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/stats/hits/{path_id}
Get an overview of referral information for a path.
§
200 OK
handlers.apiRefsResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/stats/total
Count total number of pageviews for a date range.
§
This is mostly useful to display things like browser stats as a percentage of the total; the /api/v0/pages endpoint only counts the pageviews until it's paginated.
200 OK
goatcounter.TotalCount
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/stats/{page}
Get browser/system/etc. stats.
§
Page can be: browsers, systems, locations, languages, sizes, campaigns, toprefs.
200 OK
handlers.apiStatsResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/stats/{page}/{id}
Get detailed stats for an ID.
§
Page can be: browsers, systems, locations, sizes, campaigns, toprefs.
200 OK
handlers.apiStatsResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
GET /api/v0/me
Get information about the current user and API key.
§
200 OK
handlers.meResponse
(application/json)
400 Bad Request
handlers.apiError
(application/json)
401 Unauthorized
handlers.authError
(application/json)
403 Forbidden
handlers.authError
(application/json)
Number of visitors for the selected date range.
Path ID
Path name (e.g. /hello.html).
Is this an event?
Page title.
Highest visitors per hour or day (depending on daily being set).
Statistics by day and hour.
What kind of referral this is; only set when retrieving referrals .
h HTTP Referal header. g Generated; for example are Google domains (google.com, google.nl, google.co.nz, etc.) are grouped as the generated referral "Google". c Campaign (via query parameter) o Other
Day these statistics are for.
Visitors per hour.
Total visitors for this day.
ID for selecting more details; not present in the detail view.
Display name.
Number of visitors.
What kind of referral this is; only set when retrieving referrals .
h HTTP Referal header. g Generated; for example are Google domains (google.com, google.nl, google.co.nz, etc.) are grouped as the generated referral "Google". c Campaign (via query parameter) o Other
Path ID
Path name
Page title
Is this an event?
Custom domain, e.g. "stats.example.com".
When self-hosting this is the domain/vhost your site is accessible at.
When the CNAME was verified.
Domain code (e.g. "arp242", which makes arp242.goatcounter.com). Only used for goatcounter.com and not when self-hosting.
Site domain for linking (www.arp242.net).
Whether this site has received any data; will be true after the first pageview.
SiteSettings contains all the user-configurable settings for a site, with the exception of the domain settings. This is stored as JSON in the database.
Total number of visitors (including events).
Total number of visitors for events.
Total number of visitors in UTC. The browser, system, etc, stats are always in UTC.
User entry.
Keep track when the last email report was sent, so we don't double-send them.
UserSettings are all user preferences.
"week", "week-cur", or n days: "8"
By default it's an error to send pageviews that don't have either a Session or UserAgent and IP set. This avoids accidental errors.
When this is set it will just continue without recording sessions for pageviews that don't have these parameters set.
Filter pageviews; accepted values:
ip Ignore requests coming from IP addresses listed in "Settings → Ignore IP". Requires the IP field to be set.
["ip"] is used if this field isn't sent; send an empty array ([]) to not filter anything.
The X-Goatcounter-Filter header will be set to a list of indexes if any pageviews are filtered; for example:
X-Goatcounter-Filter: 5, 10
This header will be omitted if nothing is filtered.
Hits is the list of pageviews.
Path of the pageview, or the event name.
Page title, or some descriptive event title.
Is this an event?
Referrer value, can be an URL (i.e. the Referal: header) or any string.
Screen size as "x,y,scaling"
Query parameters for this pageview, used to get campaign parameters.
Hint if this should be considered a bot; should be one of the JSBot*` constants from isbot; note the backend may override this if it detects a bot using another method. https://github.com/zgoat/isbot/blob/master/isbot.go#L28
User-Agent header.
Location as ISO-3166-1 alpha2 string (e.g. NL, ID, etc.)
IP to get location from; not used if location is set. Also used for session generation.
Time this pageview should be recorded at; this can be in the past, but not in the future.
Normally a session is based on hash(User-Agent+IP+salt), but if you don't send the IP address then we can't determine the session.
In those cases, you can store your own session identifiers and send them along. Note these will not be stored in the database as the sessionID (just as the hashes aren't), they're just used as a unique grouping identifier.
Start time, should be rounded to the hour.
End time, should be rounded to the hour.
Include only these paths; default is to include everything.
Generic API error. An error will have either the "error" or "errors" field set, but not both.
Pagination cursor; only export hits with an ID greater than this.
Start time, should be rounded to the hour.
End time, should be rounded to the hour.
Group by day, rather than by hour. This only affects the Hits.Max value: if enabled it's set to the highest value for that day, rather than the highest value for the hour.
Include only these paths; default is to include everything.
Exclude these paths, for pagination.
Maximum number of pages to get.
Sorted list of paths with their visitor and pageview count.
Total number of visitors in the returned result.
More hits after this?
Limit number of returned results
Only select paths after this ID, for pagination.
List of paths, sorted by ID.
True if there are more paths.
Start time, should be rounded to the hour.
End time, should be rounded to the hour.
Maximum number of pages to get.
Offset for pagination.
Start time, should be rounded to the hour.
End time, should be rounded to the hour.
Include only these paths; default is to include everything.
Maximum number of pages to get.
Offset for pagination.
Sorted list of paths with their visitor and pageview count.
Authentication error: the API key was not provided or incorrect.
A Location maps time instants to the zone in use at that time. Typically, the Location represents the collection of time offsets in use in a geographical area. For many Locations the time offset varies depending on whether daylight savings time is in use at the time instant.
Zone represents a time zone.
ID
Asia/Makassar
WITA – the correct abbreviation may change depending on the time of year (i.e. CET and CEST, depending on DST).
Indonesia
Borneo (east, south); Sulawesi/Celebes, Bali, Nusa Tengarra; Timor (west)
The hit ID this export was started from.
Last hit ID that was exported; can be used as start_from_hit_id.
File size in MB.
SHA256 hash.
Any errors that may have occured.