Audience

Audience endpoints use flat reporting query parameters: GET https://data.goodmetrics.io/{gmID}/events/audience/{resource}?start={start}&end={end}.

Example:

curl

curl "https://data.goodmetrics.io/{gmID}/events/audience/countries?start=1771872000&end=1772476799&page=1&limit=10&sort_by=uniqueVisitors&dir=desc&country_is=Canada" \
  -H "Authorization: Bearer YOUR_API_KEY"

Node

const gmID = '{gmID}';
const apiKey = 'YOUR_API_KEY';
const params = new URLSearchParams({
  "start": "1771872000",
  "end": "1772476799",
  "page": "1",
  "limit": "10",
  "sort_by": "uniqueVisitors",
  "dir": "desc",
  "country_is": "Canada"
});

const response = await fetch(`https://data.goodmetrics.io/${gmID}/events/audience/countries?${params}`, {
  headers: {
    Authorization: `Bearer ${apiKey}`
  }
});

console.log(await response.json());

Python

import json
import urllib.parse
import urllib.request

gm_id = "{gmID}"
api_key = "YOUR_API_KEY"
params = urllib.parse.urlencode({
    "start": "1771872000",
    "end": "1772476799",
    "page": "1",
    "limit": "10",
    "sort_by": "uniqueVisitors",
    "dir": "desc",
    "country_is": "Canada"
})

request = urllib.request.Request(
    f"https://data.goodmetrics.io/{gm_id}/events/audience/countries?{params}",
    headers={"Authorization": f"Bearer {api_key}"},
)

with urllib.request.urlopen(request) as response:
    print(json.load(response))

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

class GoodMetricsExample {
  public static void main(String[] args) throws Exception {
    var gmID = "{gmID}";
    var apiKey = "YOUR_API_KEY";
    var url = "https://data.goodmetrics.io/" + gmID + "/events/audience/countries?start=1771872000&end=1772476799&page=1&limit=10&sort_by=uniqueVisitors&dir=desc&country_is=Canada";

    var request = HttpRequest.newBuilder()
      .uri(URI.create(url))
      .header("Authorization", "Bearer " + apiKey)
      .GET()
      .build();

    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  }
}

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Net.Http.Headers;

var gmID = "{gmID}";
var apiKey = "YOUR_API_KEY";
var query = new Dictionary<string, string>
{
  ["start"] = "1771872000",
  ["end"] = "1772476799",
  ["page"] = "1",
  ["limit"] = "10",
  ["sort_by"] = "uniqueVisitors",
  ["dir"] = "desc",
  ["country_is"] = "Canada"
};
var queryString = string.Join("&", query.Select(parameter =>
  $"{Uri.EscapeDataString(parameter.Key)}={Uri.EscapeDataString(parameter.Value)}"));

var url = $"https://data.goodmetrics.io/{gmID}/events/audience/countries?{queryString}";

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

using var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$gmID = "{gmID}";
$apiKey = "YOUR_API_KEY";
$params = http_build_query([
    "start" => "1771872000",
    "end" => "1772476799",
    "page" => "1",
    "limit" => "10",
    "sort_by" => "uniqueVisitors",
    "dir" => "desc",
    "country_is" => "Canada"
]);

$url = "https://data.goodmetrics.io/{$gmID}/events/audience/countries?{$params}";

$context = stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Authorization: Bearer {$apiKey}\r\n",
    ],
]);

$response = file_get_contents($url, false, $context);
echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
)

func main() {
  gmID := "{gmID}"
  apiKey := "YOUR_API_KEY"

  params := url.Values{}
  params.Set("start", "1771872000")
  params.Set("end", "1772476799")
  params.Set("page", "1")
  params.Set("limit", "10")
  params.Set("sort_by", "uniqueVisitors")
  params.Set("dir", "desc")
  params.Set("country_is", "Canada")

  request, _ := http.NewRequest(
    "GET",
    "https://data.goodmetrics.io/"+gmID+"/events/audience/countries?"+params.Encode(),
    nil,
  )
  request.Header.Set("Authorization", "Bearer "+apiKey)

  response, _ := http.DefaultClient.Do(request)
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Overview endpoints

Overview endpoints return compact breakdowns for dashboards and summaries.

Endpoint	Description
GET /{gmID}/events/audience/overview/browsers	Browser overview.
GET /{gmID}/events/audience/overview/cities	City overview.
GET /{gmID}/events/audience/overview/countries	Country overview.
GET /{gmID}/events/audience/overview/devices	Device overview.
GET /{gmID}/events/audience/overview/languages	Language overview.
GET /{gmID}/events/audience/overview/operating-systems	Operating system overview.
GET /{gmID}/events/audience/overview/regions	Region overview.
GET /{gmID}/events/audience/overview/new-vs-returning	New versus returning visitor overview.

Table endpoints

Table endpoints return paginated standard table responses with meta.cursor, meta.totals, and data.primary.

Endpoint	Alignment key
GET /{gmID}/events/audience/countries	country
GET /{gmID}/events/audience/regions	region
GET /{gmID}/events/audience/cities	city
GET /{gmID}/events/audience/languages	language
GET /{gmID}/events/audience/browsers	browser
GET /{gmID}/events/audience/operating-systems	operatingSystem
GET /{gmID}/events/audience/devices	device

Common response metrics include sessions, uniqueVisitors, newVisitors, avgSessionLength, bounceRate, pagesPerSession, eventCompletions, eventValue, and eventConversionRate.

See Common Recipes for more request examples.