API Overview

Programmatically access your Ghost Metrics analytics data.

Introduction

The Ghost Metrics API allows you to programmatically request analytics reports, manage websites, users, goals, and more. You can retrieve data in multiple formats (JSON, XML, CSV) and integrate Ghost Metrics data into your own applications, dashboards, or automated workflows.

What You Can Do

Reporting API

Retrieve analytics data programmatically:

• Visitor data — Visits, unique visitors, returning visitors
• Behavior data — Page views, downloads, outlinks, site search
• Acquisition data — Referrers, search engines, campaigns
• Goal data — Conversions, revenue, goal completions
• Real-time data — Current visitors, live actions

Management API

Manage your Ghost Metrics configuration:

• Websites — List and manage tracked websites
• Goals — Create, update, and delete goals
• Segments — Manage saved segments
• Users — User management (admin only)
• Scheduled Reports — Configure automated reports

API Endpoint

All API requests are made to your Ghost Metrics instance:

https://[your-subdomain].ghostmetrics.cloud/

For example:

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

Response Formats

The API supports multiple output formats:

JSON Example Response

{
  "nb_uniq_visitors": 1250,
  "nb_visits": 1543,
  "nb_actions": 4521,
  "bounce_rate": "45%",
  "avg_time_on_site": 185
}

Quick Start

Here’s a simple example to get yesterday’s visit summary:

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

Parameters explained:

• module=API — Required for all API calls
• method=VisitsSummary.get — The API method to call
• idSite=1 — Your website ID
• period=day — Time period (day, week, month, year, range)
• date=yesterday — The date to query
• format=JSON — Response format
• token_auth — Your authentication token

Finding Your API Credentials

Website ID (idSite)

1. Log into Ghost Metrics
2. Go to Administration → Websites → Manage
3. Find your website in the list
4. The ID is shown in the first column

Authentication Token

1. Log into Ghost Metrics
2. Go to Administration → Personal → Security
3. Under Auth tokens, create a new token
4. Copy and securely store the token

See Authentication for detailed instructions.

API Modules

The API is organized into modules, each handling different functionality:

Core Analytics Modules

Premium Feature Modules

Management Modules

Discovering the API

Two meta-methods make the whole API self-describing:

• API.getReportMetadata — Lists every available report with its dimensions and metrics
• API.getProcessedReport — Returns any report in a human-readable form, including processed metrics like conversion rates

Usage Limits

There are no hard per-request rate limits, but heavy automated workloads (very large exports, tight polling loops) can affect report processing. Prefer bulk requests for batches, and contact support if you’re planning high-volume integrations.

Security Best Practices

1. Never expose your token in client-side code or public repositories
2. Use HTTPS for all API requests
3. Create dedicated tokens for different applications
4. Use POST requests for tokens when possible
5. Rotate tokens periodically

Next Steps

• Authentication — Set up API access
• Making Requests — Learn request structure
• Parameters Reference — All available parameters
• Common Methods — Most-used API methods
• Code Examples — Working code samples