GoatCounter API documentation 0.1

Endpoints

count

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.

Request body

Responses

export

GET /api/v0/export/{id} Get details about an export.

Responses

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.

Responses

POST /api/v0/export Start a new export in the background.

This starts a new export in the background.

Request body

Responses

sites

GET /api/v0/sites List all sites.

Responses

GET /api/v0/sites/{id} Get information about a site.

Get all information about one site.

Responses

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.

Request body

Responses

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.

Request body

Responses

PUT /api/v0/sites Create a new site.

Request body

Responses

user

GET /api/v0/me Get information about the current user and API key.

Responses

Models

goatcounter.APIToken

name string

permissions integer

goatcounter.Export

id integer [readonly]

site_id integer [readonly]

start_from_hit_id integer

The hit ID this export was started from.

last_hit_id integer [readonly]

Last hit ID that was exported; can be used as start_from_hit_id.

created_at string [format: date-time] [readonly]

finished_at string [format: date-time] [readonly]

num_rows integer [readonly]

size string [readonly]

File size in MB.

hash string [readonly]

SHA256 hash.

error string [readonly]

Any errors that may have occured.

goatcounter.Site

id integer [readonly]

parent integer [readonly]

cname string

Custom domain, e.g. "stats.example.com".

When self-hosting this is the domain/vhost your site is accessible at.

cname_setup_at string [format: date-time] [readonly]

When the CNAME was verified.

code string

Domain code (e.g. "arp242", which makes arp242.goatcounter.com). Only used for goatcounter.com and not when self-hosting.

link_domain string

Site domain for linking (www.arp242.net).

plan string [readonly]

Plan currently subscribed to.

plan_pending string [readonly]

Plan this site tried to subscribe to, but payment hasn't been verified yet.

stripe string [readonly]

Stripe customer ID.

plan_cancel_at string [format: date-time] [readonly]

When this plan is scheduled to be cancelled.

billing_amount string [readonly]

Amount is being paid for the plan.

extra_pageviews integer [readonly]

Maximum number of extra pageviews to charge for.

billing_anchor string [format: date-time] [readonly]

"Anchor" for the billing period.

This is the time someone subscribed to a plan; and their billing period will start on this day.

setttings

user_defaults

received_data boolean

Whether this site has received any data; will be true after the first pageview.

state string

created_at string [format: date-time]

updated_at string [format: date-time]

first_hit_at string [format: date-time]

goatcounter.SiteSettings

SiteSettings contains all the user-configurable settings for a site, with the exception of the domain and billing settings. This is stored as JSON in the database.

public boolean

allow_counter boolean

allow_bosmang boolean

data_retention integer

campaigns array [type: string]

ignore_ips array [type: string]

collect integer

collect_regions array [type: string]

goatcounter.User

User entry.

id integer [readonly]

site integer [readonly]

email string

email_verified boolean [readonly]

totp_enabled boolean [readonly]

access [readonly]

login_at string [format: date-time] [readonly]

reset_at string [format: date-time] [readonly]

settings

created_at string [format: date-time] [readonly]

updated_at string [format: date-time] [readonly]

goatcounter.UserSettings

UserSettings are all user preferences.

twenty_four_hours boolean

sunday_starts_week boolean

date_format string

number_format string

timezone

widgets array [type: goatcounter.Widget]

views array [type: goatcounter.View]

goatcounter.View

name string

filter string

daily boolean

period string

"week", "week-cur", or n days: "8"

goatcounter.Widget

handlers.APICountRequest

no_sessions boolean

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 array [type: string]

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 array [type: handlers.APICountRequestHit]

Hits is the list of pageviews.

handlers.APICountRequestHit

path string [required]

Path of the pageview, or the event name.

title string

Page title, or some descriptive event title.

event boolean

Is this an event?

ref string

Referrer value, can be an URL (i.e. the Referal: header) or any string.

size array [type: number]

Screen size as "x,y,scaling"

query string

Query parameters for this pageview, used to get campaign parameters.

bot integer

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 string

User-Agent header.

location string

Location as ISO-3166-1 alpha2 string (e.g. NL, ID, etc.)

ip string

IP to get location from; not used if location is set. Also used for session generation.

created_at string [format: date-time]

Time this pageview should be recorded at; this can be in the past, but not in the future.

session string

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.

handlers.apiError

error string

errors

handlers.apiExportRequest

start_from_hit_id integer

Pagination cursor; only export hits with an ID greater than this.

handlers.apiSiteUpdateRequest

settings

cname string

link_domain string

handlers.apiSitesResponse

sites array [type: goatcounter.Site]

handlers.authError

Error string

handlers.meResponse

user

token

time.Location

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.

tz.Zone

Zone represents a time zone.

CountryCode string

ID

Zone string

Asia/Makassar

Abbr array [type: string]

WITA – the correct abbreviation may change depending on the time of year (i.e. CET and CEST, depending on DST).

CountryName string

Indonesia

Comments string

Borneo (east, south); Sulawesi/Celebes, Bali, Nusa Tengarra; Timor (west)