Skip to Content
APICode Examples

Code Examples

Working code samples for common API tasks.

PHP

Basic Request

<?php
$token = 'YOUR_TOKEN_HERE';
$baseUrl = 'https://example.ghostmetrics.cloud/';
 
$url = $baseUrl . '?' . http_build_query([
    'module' => 'API',
    'method' => 'VisitsSummary.get',
    'idSite' => 1,
    'period' => 'day',
    'date' => 'yesterday',
    'format' => 'JSON',
    'token_auth' => $token
]);
 
$response = file_get_contents($url);
$data = json_decode($response, true);
 
echo "Visits: " . $data['nb_visits'] . "\n";
echo "Unique Visitors: " . $data['nb_uniq_visitors'] . "\n";
echo "Bounce Rate: " . $data['bounce_rate'] . "\n";

POST Request (More Secure)

<?php
$token = 'YOUR_TOKEN_HERE';
$baseUrl = 'https://example.ghostmetrics.cloud/';
 
$params = [
    'module' => 'API',
    'method' => 'VisitsSummary.get',
    'idSite' => 1,
    'period' => 'day',
    'date' => 'yesterday',
    'format' => 'JSON',
    'token_auth' => $token
];
 
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $baseUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
$response = curl_exec($ch);
curl_close($ch);
 
$data = json_decode($response, true);
print_r($data);

Get Top Pages

<?php
function getTopPages($siteId, $token, $limit = 10) {
    $baseUrl = 'https://example.ghostmetrics.cloud/';
    
    $params = [
        'module' => 'API',
        'method' => 'Actions.getPageUrls',
        'idSite' => $siteId,
        'period' => 'month',
        'date' => 'today',
        'format' => 'JSON',
        'filter_limit' => $limit,
        'token_auth' => $token
    ];
    
    $url = $baseUrl . '?' . http_build_query($params);
    $response = file_get_contents($url);
    
    return json_decode($response, true);
}
 
$pages = getTopPages(1, 'YOUR_TOKEN');
 
foreach ($pages as $page) {
    echo $page['label'] . ': ' . $page['nb_visits'] . " visits\n";
}

Python

Basic Request

import requests
 
TOKEN = 'YOUR_TOKEN_HERE'
BASE_URL = 'https://example.ghostmetrics.cloud/'
 
params = {
    'module': 'API',
    'method': 'VisitsSummary.get',
    'idSite': 1,
    'period': 'day',
    'date': 'yesterday',
    'format': 'JSON',
    'token_auth': TOKEN
}
 
response = requests.get(BASE_URL, params=params)
data = response.json()
 
print(f"Visits: {data['nb_visits']}")
print(f"Unique Visitors: {data['nb_uniq_visitors']}")
print(f"Bounce Rate: {data['bounce_rate']}")

POST Request (More Secure)

import requests
 
TOKEN = 'YOUR_TOKEN_HERE'
BASE_URL = 'https://example.ghostmetrics.cloud/'
 
params = {
    'module': 'API',
    'method': 'VisitsSummary.get',
    'idSite': 1,
    'period': 'day',
    'date': 'yesterday',
    'format': 'JSON',
    'token_auth': TOKEN
}
 
response = requests.post(BASE_URL, data=params)
data = response.json()
print(data)

Reusable API Class

import requests
from typing import Optional, Dict, Any
 
class GhostMetricsAPI:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url.rstrip('/')
        self.token = token
    
    def _request(self, method: str, **kwargs) -> Dict[str, Any]:
        params = {
            'module': 'API',
            'method': method,
            'format': 'JSON',
            'token_auth': self.token,
            **kwargs
        }
        response = requests.post(self.base_url, data=params)
        response.raise_for_status()
        return response.json()
    
    def get_visits_summary(self, site_id: int, period: str = 'day', 
                          date: str = 'yesterday') -> Dict[str, Any]:
        return self._request(
            'VisitsSummary.get',
            idSite=site_id,
            period=period,
            date=date
        )
    
    def get_top_pages(self, site_id: int, period: str = 'month',
                     date: str = 'today', limit: int = 10) -> list:
        return self._request(
            'Actions.getPageUrls',
            idSite=site_id,
            period=period,
            date=date,
            filter_limit=limit
        )
    
    def get_traffic_sources(self, site_id: int, period: str = 'month',
                           date: str = 'today') -> list:
        return self._request(
            'Referrers.getReferrerType',
            idSite=site_id,
            period=period,
            date=date
        )
    
    def get_countries(self, site_id: int, period: str = 'month',
                     date: str = 'today', limit: int = 10) -> list:
        return self._request(
            'UserCountry.getCountry',
            idSite=site_id,
            period=period,
            date=date,
            filter_limit=limit
        )
 
# Usage
api = GhostMetricsAPI('https://example.ghostmetrics.cloud/', 'YOUR_TOKEN')
 
summary = api.get_visits_summary(site_id=1)
print(f"Yesterday: {summary['nb_visits']} visits")
 
pages = api.get_top_pages(site_id=1, limit=5)
for page in pages:
    print(f"{page['label']}: {page['nb_visits']} visits")

With Segmentation

import requests
from urllib.parse import quote
 
TOKEN = 'YOUR_TOKEN_HERE'
BASE_URL = 'https://example.ghostmetrics.cloud/'
 
# Get mobile visitors from US
segment = 'deviceType==smartphone;countryCode==US'
 
params = {
    'module': 'API',
    'method': 'VisitsSummary.get',
    'idSite': 1,
    'period': 'month',
    'date': 'today',
    'format': 'JSON',
    'segment': segment,
    'token_auth': TOKEN
}
 
response = requests.get(BASE_URL, params=params)
data = response.json()
 
print(f"Mobile US Visits: {data['nb_visits']}")

JavaScript (Node.js)

Basic Request

const https = require('https');
 
const TOKEN = 'YOUR_TOKEN_HERE';
const BASE_URL = 'example.ghostmetrics.cloud';
 
const params = new URLSearchParams({
  module: 'API',
  method: 'VisitsSummary.get',
  idSite: 1,
  period: 'day',
  date: 'yesterday',
  format: 'JSON',
  token_auth: TOKEN
});
 
https.get(`https://${BASE_URL}/?${params}`, (res) => {
  let data = '';
  
  res.on('data', chunk => data += chunk);
  res.on('end', () => {
    const result = JSON.parse(data);
    console.log('Visits:', result.nb_visits);
    console.log('Unique Visitors:', result.nb_uniq_visitors);
  });
});

Using Fetch (Node.js 18+)

const TOKEN = 'YOUR_TOKEN_HERE';
const BASE_URL = 'https://example.ghostmetrics.cloud/';
 
async function getVisitsSummary(siteId, period = 'day', date = 'yesterday') {
  const params = new URLSearchParams({
    module: 'API',
    method: 'VisitsSummary.get',
    idSite: siteId,
    period: period,
    date: date,
    format: 'JSON',
    token_auth: TOKEN
  });
 
  const response = await fetch(`${BASE_URL}?${params}`);
  return response.json();
}
 
async function getTopPages(siteId, limit = 10) {
  const params = new URLSearchParams({
    module: 'API',
    method: 'Actions.getPageUrls',
    idSite: siteId,
    period: 'month',
    date: 'today',
    format: 'JSON',
    filter_limit: limit,
    token_auth: TOKEN
  });
 
  const response = await fetch(`${BASE_URL}?${params}`);
  return response.json();
}
 
// Usage
(async () => {
  const summary = await getVisitsSummary(1);
  console.log(`Visits: ${summary.nb_visits}`);
  
  const pages = await getTopPages(1, 5);
  pages.forEach(page => {
    console.log(`${page.label}: ${page.nb_visits} visits`);
  });
})();

cURL

Basic Request

curl "https://example.ghostmetrics.cloud/?module=API&method=VisitsSummary.get&idSite=1&period=day&date=yesterday&format=JSON&token_auth=YOUR_TOKEN"

POST Request

curl -X POST "https://example.ghostmetrics.cloud/" \
  -d "module=API" \
  -d "method=VisitsSummary.get" \
  -d "idSite=1" \
  -d "period=day" \
  -d "date=yesterday" \
  -d "format=JSON" \
  -d "token_auth=YOUR_TOKEN"

With Segmentation

curl "https://example.ghostmetrics.cloud/?module=API&method=VisitsSummary.get&idSite=1&period=month&date=today&format=JSON&segment=deviceType%3D%3Dsmartphone&token_auth=YOUR_TOKEN"

Pretty Print JSON

curl -s "https://example.ghostmetrics.cloud/?module=API&method=VisitsSummary.get&idSite=1&period=day&date=yesterday&format=JSON&token_auth=YOUR_TOKEN" | python -m json.tool

Bulk Requests

Get Multiple Reports at Once

import requests
from urllib.parse import quote
 
TOKEN = 'YOUR_TOKEN_HERE'
BASE_URL = 'https://example.ghostmetrics.cloud/'
 
# Define the requests to make
requests_to_make = [
    'method=VisitsSummary.get&idSite=1&period=day&date=yesterday',
    'method=UserCountry.getCountry&idSite=1&period=day&date=yesterday&filter_limit=5',
    'method=Referrers.getReferrerType&idSite=1&period=day&date=yesterday'
]
 
# URL encode each request
encoded_requests = [quote(req, safe='') for req in requests_to_make]
 
params = {
    'module': 'API',
    'method': 'API.getBulkRequest',
    'format': 'JSON',
    'token_auth': TOKEN
}
 
# Add the requests as urls[] parameters
for i, req in enumerate(encoded_requests):
    params[f'urls[{i}]'] = req
 
response = requests.get(BASE_URL, params=params)
results = response.json()
 
# Results is an array with each request's response
visits_summary = results[0]
countries = results[1]
traffic_sources = results[2]
 
print(f"Total visits: {visits_summary['nb_visits']}")
print(f"Top country: {countries[0]['label']}")
print(f"Top source: {traffic_sources[0]['label']}")

Error Handling

Python with Error Handling

import requests
 
def api_request(method, **kwargs):
    BASE_URL = 'https://example.ghostmetrics.cloud/'
    TOKEN = 'YOUR_TOKEN_HERE'
    
    params = {
        'module': 'API',
        'method': method,
        'format': 'JSON',
        'token_auth': TOKEN,
        **kwargs
    }
    
    try:
        response = requests.get(BASE_URL, params=params, timeout=30)
        response.raise_for_status()
        
        data = response.json()
        
        # Check for API-level errors
        if isinstance(data, dict) and data.get('result') == 'error':
            raise Exception(f"API Error: {data.get('message')}")
        
        return data
        
    except requests.exceptions.Timeout:
        raise Exception("Request timed out")
    except requests.exceptions.RequestException as e:
        raise Exception(f"Request failed: {e}")
    except ValueError:
        raise Exception("Invalid JSON response")
 
# Usage
try:
    data = api_request('VisitsSummary.get', idSite=1, period='day', date='yesterday')
    print(f"Visits: {data['nb_visits']}")
except Exception as e:
    print(f"Error: {e}")

Scheduled Reporting

Python Script for Daily Reports

#!/usr/bin/env python3
"""
Daily analytics report script.
Run via cron: 0 8 * * * /path/to/daily_report.py
"""
 
import requests
import smtplib
from email.mime.text import MIMEText
from datetime import datetime
 
# Configuration
TOKEN = 'YOUR_TOKEN_HERE'
BASE_URL = 'https://example.ghostmetrics.cloud/'
SITE_ID = 1
EMAIL_TO = 'team@example.com'
 
def get_yesterday_summary():
    params = {
        'module': 'API',
        'method': 'VisitsSummary.get',
        'idSite': SITE_ID,
        'period': 'day',
        'date': 'yesterday',
        'format': 'JSON',
        'token_auth': TOKEN
    }
    response = requests.get(BASE_URL, params=params)
    return response.json()
 
def get_top_pages():
    params = {
        'module': 'API',
        'method': 'Actions.getPageUrls',
        'idSite': SITE_ID,
        'period': 'day',
        'date': 'yesterday',
        'format': 'JSON',
        'filter_limit': 5,
        'token_auth': TOKEN
    }
    response = requests.get(BASE_URL, params=params)
    return response.json()
 
def generate_report():
    summary = get_yesterday_summary()
    pages = get_top_pages()
    
    report = f"""
Daily Analytics Report - {datetime.now().strftime('%Y-%m-%d')}
{'=' * 50}
 
SUMMARY
-------
Visits: {summary['nb_visits']}
Unique Visitors: {summary['nb_uniq_visitors']}
Page Views: {summary['nb_actions']}
Bounce Rate: {summary['bounce_rate']}
Avg. Time on Site: {summary['avg_time_on_site']} seconds
 
TOP 5 PAGES
-----------
"""
    
    for i, page in enumerate(pages[:5], 1):
        report += f"{i}. {page['label']}: {page['nb_visits']} visits\n"
    
    return report
 
def send_email(report):
    msg = MIMEText(report)
    msg['Subject'] = f"Daily Analytics Report - {datetime.now().strftime('%Y-%m-%d')}"
    msg['From'] = 'analytics@example.com'
    msg['To'] = EMAIL_TO
    
    # Configure your SMTP settings
    with smtplib.SMTP('smtp.example.com', 587) as server:
        server.starttls()
        server.login('user', 'password')
        server.send_message(msg)
 
if __name__ == '__main__':
    report = generate_report()
    print(report)
    # send_email(report)  # Uncomment to send email

Next Steps

Last updated on
Common API MethodsFAQ