---
title: Services
date: 2026-07-02T15:09:00+01:00
author: John Henry Donovan
canonical_url: "https://johnhenry.ie/plugins/clicky-analytics/docs/api-reference/services"
section: Plugins
---
esc

↑↓ to navigate↵ to selectesc to close

Menu On this page 

- [Return to top](#)

Documentation

Documentation

# Services

## `Api`

`johnhenry\clickyanalytics\services\Api` is the plugin's single service. It wraps the [Clicky stats API](https://clicky.com/help/api): a low-level request method packs one or more report "types" into each call, normalises Clicky's nested `[{type, dates:[{items:[…]}]}]` response into flat arrays, decorates rows with flags and logos, and caches results for the configured duration.

```php
$api = ClickyAnalytics::getInstance()->getApi();
```

Every method that performs a request throws `\RuntimeException` if the plugin is unconfigured or the API returns an error, except `ping()`, which returns a structured result instead.

### Configuration & connectivity

MethodReturnsNotes`isConfigured(): bool`Whether both a Site ID and a Sitekey are set.Never throws.`ping(string $siteId, string $siteKey): array``{success: bool, message: string}`Tests a credential pair independently of saved settings; backs the **Test connection **button.****

### Low-level

MethodReturns`getStats(array $types, string $date, array $params = []): array`Items keyed by report type.`getTally(string $type, string $date): int`The single scalar value of a tally report type.`getDailySeries(string $type, string $date): array`A per-day series (oldest first) for charting.`getReport(string $type, string $date, int $limit = 10): array`A ranked report by Clicky type, routing to the enriched `getTop*` method when one exists. Backs the configurable Report widget.

### Headline metrics

MethodReturns`getVisitorsOnline(): int`Visitors online now.`getNewVsReturning(string $date): array``{new, returning, total}.``getOverview(string $date, ?string $previousDate = null): array`Visitors, actions, bounce rate and average time, each with an optional period-over-period trend.

### Ranked reports

All take `(string $date, int $limit = 10)` unless noted.

MethodReport`getTopPages`Pages`getTopSources`Traffic sources`getTopReferrers`Referring domains`getTopSearchEngines`Search engines (grouped by brand, with logos)`getTopCountries($date, $limit, $withDrilldown = false)`Countries (with ISO `code`; `canDrill` flag when `$withDrilldown`)`getTopCities / getTopRegions`Cities / regions`getTopBrowsers($date, $limit, ?bool $consolidate = null)`Browsers (consolidates versions by default; with logos)`getTopOperatingSystems($date, $limit, ?bool $consolidate = null)`Operating systems (consolidates versions by default; with logos)`getTopDevices`Hardware device types (with a device icon)`getTopScreenResolutions`Screen resolutions`getEntryPages / getExitPages`Landing / exit pages`getTopDownloads`Downloads`getTopGoals`Goal completions`getTopCampaigns`Campaigns

### Country drilldown

MethodReturns`getCountryBreakdown(string $country, string $date, int $limit = 5): array``{cities, regions}` for a single country (filtered client-side from the global lists).`getCountriesWithBreakdown(string $date): array`A lookup of countries that have any city/region data, so the UI shows the drilldown only where there's something to expand.

### Visitors & pages

MethodReturns`getRecentVisitors(string $date = 'last-7-days', int $limit = 12): array`Normalised recent-visitor rows (location, flag, browser/OS logos, referrer, duration, new vs returning).`getPageStats(string $href, string $date, int $visitorLimit = 5): array`Headline tallies, traffic sources and recent visitors for a single page path. Backs the page-stats field.

## Caching

Responses are cached under a key derived from the Site ID, the requested types, the date expression and any extra params, for `Settings::$cacheDuration` seconds. Set the duration to `0` to disable caching entirely.

On this page