Export format

The GoatCounter export is a CSV export of all pageviews of a site.

There is no “standard” CSV; the export is created with the encoding/csv package. Some notes:

  • The first line is the header.
  • Blank lines are allowed; lines may end with \n or \r\n.
  • Optionally quote fields with ": hello,"world"
  • Escape a " inside a quoted field by doubling it up: hello,"""world"""
  • Newlines inside quoted fields are allowed.

CSV format

The first line is a header with the field names. The fields, in order, are:

2,PathPath name (e.g. /a.html). This also doubles as the event name. This header is prefixed with the version export format (see versioning below).
TitlePage title that was sent.
EventIf this is an event; true or false.
User-AgentUser-Agent header.
BrowserBrowser name and version.
SystemSystem name and version.
SessionThe session ID, to track unique visitors.
BotIf this is a bot request; 0 if it's not, or one of the isbot constants if it is.
ReferrerReferrer data.
Referrer scheme h – HTTP; an URL;
g – Generated; e.g. all the various Hacker News interfaces don't add a link to the specific story, so are just recorded as “Hacker News”;
c – Campaign; text string from a campaign parameter;
o – Other (e.g. Android apps).
Screen sizeScreen size as x,y,scaling.
LocationISO 3166-2 country code (either "US" or "US-TX")
FirstVisitFirst visit in this session?
DateCreation date as RFC 3339/ISO 8601.

Versioning

The format of the CSV file may change in the future; the version of the export file is recorded at the start of the header as a number. It’s strongly recommended to check this number if you’re using a script to import/sync data and error out if it changes. Any future incompatibilities will be documented here.

Version 1 documentation

The first line is a header with the field names. The fields, in order, are:

1,PathPath name (e.g. /a.html). This also doubles as the event name. This header is prefixed with the version export format (see versioning below).
TitlePage title that was sent.
EventIf this is an event; true or false.
BotIf this is a bot request; 0 if it’s not, or one of the isbot constants if it is.
SessionThe session ID, to track unique visitors.
FirstVisitFirst visit in this session?
ReferrerReferrer data.
Referrer scheme h – HTTP; an URL;
g – Generated; e.g. all the various Hacker News interfaces don’t add a link to the specific story, so are just recorded as “Hacker News”;
c – Campaign; text string from a campaign parameter;
o – Other (e.g. Android apps).
BrowserUser-Agent header.
Screen sizeScreen size as x,y,scaling.
LocationISO 3166-1 country code.
DateCreation date as RFC 3339/ISO 8601.

Importing in SQL

If you want to run analytics on this, you can use e.g. 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;
┌────────┬──────────┐
│ count  │ location │
├────────┼──────────┤
│ 113144 │ US       │
│ 27092  │ DE       │
│ 24131  │ GB       │
│ 13269  │ CA       │
│ 12977  │ FR       │
│ 9785   │ NL       │
│ 8150   │ IN       │
│ 7487   │ AU       │
│ 6864   │ PL       │
│ 6760   │ SE       │
└────────┴──────────┘

Or 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);

Questions or problems?

Feel free to get in touch if you’ve got any questions or having any problems; a lot of times they can be resolved without too much problems.

Ways to contact me: show