umami-api-client

Umami ReST API.

• compatible with JavaScript.

Note that a typescript compatible API client exists (but deprecated/archived) : cf. https://github.com/jakobbouchard/umami-api-client

UmamiClient

Features

using apiKey:

• login
• getSites
• getStats, getPageViews, getEvents, getMetrics

accepted periods are : 1h, 1d, 7d, 30d, 31d.

Quick start

First, set up your environment :

cp ./env/initenv_cloud.template.sh ./env/initenv_cloud.dontpush.sh
# update ./env/initenv_cloud.dontpush.sh
. ./env/initenv_cloud.dontpush.sh

install umami-api-client

pnpm install umami-api-client
# or
npm install umami-api-client

then let's go, cf. example below.

HowTo use UmamiClient with Umami Cloud server ?

Umami Cloud is "Umami as a service" : cf. https://cloud.umami.is/

Rely on following mandatory variable (setup your own) : UMAMI_CLOUD_API_KEY

NOTE: when an API key is set, the cloud mode is always activated (!) prior to hosted mode. To use hosted mode, you will have to unset UMAMI_CLOUD_API_KEY or use explicit config.

$ node.exe ./tests/manual/cloud_sample.js

import UmamiClient from 'umami-api-client';

const doIt = async () => {
    try {
        const client = new UmamiClient();
        // default is // new UmamiClient({cloudApiKey:process.env.UMAMI_CLOUD_API_KEY});
        const identity = await client.me();
        console.log(`🔑 Api key details:\n${JSON.stringify(identity?.user,null,2)}`);

        const sitesData = await client.websites();
        const filteredSitesData = sitesData.map(({ id, name, createdAt, domain }) => ({ id, name, createdAt, domain }));
        console.log("🗂️ List of Tracked Websites:");
        console.table(filteredSitesData);

        const websiteStats = await client.websiteStats(sitesData[0].id);
        console.log(`📊 Website Stats for: ${sitesData[0].name}`);
        console.table(websiteStats);
    } catch(error) {
        console.error(error);
    }
};

doIt().then(r => {});

HowTo use UmamiClient with an Umami hosted server ?

Umami hosted server is a server with umami product hosted by you or by a company which is not Umami (or for ex. locally using docker).

So a URL is available to query Umami hosted server (aka UMAMI_SERVER). Ex. https://umami.exemple.com

By default, UmamiClient rely on following environment variables : UMAMI_SERVER UMAMI_USER UMAMI_PASSWORD

$ node.exe ./tests/manual/host_sample.js

import UmamiClient from 'umami-api-client';

const doIt = async () => {
    try {
        const client = new UmamiClient();
        // default is // new UmamiClient({server:process.env.UMAMI_SERVER});
        await client.login();
        // default is // client.login(process.env.UMAMI_USER, process.env.UMAMI_PASSWORD)
        const sitesData = await client.websites();
        const filteredSitesData = sitesData.map(({ id, name, createdAt, domain }) => ({ id, name, createdAt, domain }));
        console.log("🗂️ List of Tracked Websites:");
        console.table(filteredSitesData);

        const websiteStats = await client.websiteStats(sitesData[0].id);
        console.log(`📊 Website Stats for: ${sitesData[0].name}`);
        console.table(websiteStats);
    } catch(error) {
        console.error(error);
    }
};

doIt().then(r => {});

Note that relying on environment is not mandatory, you could use explicit config or arguments. ex.

var client = new UmamiClient({server:'umami.exemple.com'});
await client.login("admin","mySecret");

HowTo better understand UmamiClient use ?

You could play mocha tests to get more examples (cf. CONTRIBUTING).

How to contribute

cf. CONTRIBUTING

Services or activated bots

• Github actions : continuous tests + coverage using c8 reported on github pages website
• Github security checks activated
• Houndci : JavaScript automated review (configured by .hound.yml)
• gren : Release notes automation
• Github pages website hosts some metrics for the main branch of this project: code coverage