Image API

Image API

The Statsly Image API allows you to generate dynamic SVG charts of your server’s player statistics. These charts can be embedded in websites, Discord bots, or any other application that supports SVG images.

Overview

The Image API generates beautiful, customizable line charts showing peak and average player counts over time. Charts are returned as SVG (Scalable Vector Graphics) format, making them perfect for embedding and scaling to any size.

• Dynamic SVG generation
• Customizable themes (light/dark)
• Adjustable date ranges
• Customizable dimensions
• Public and private server support
• Automatic caching for performance

Endpoints

Get Player Statistics Chart

Generate a chart for a specific server’s player statistics.

Endpoint: GET /api/servers/:id/chart/players

Authentication: Required for private servers (public servers are accessible without authentication)

URL Parameters

• id (required) - The unique server ID (UUID)

Query Parameters

Parameter	Type	Default	Range	Description
days	number	7	1-365	Number of days to include in the chart
width	number	800	200-2000	Chart width in pixels
height	number	400	200-2000	Chart height in pixels
theme	string	light	light or dark	Visual theme for the chart

Example Request

curl

curl "https://api.statsly.org/api/servers/your-server-id/chart/players?days=30&width=1200&height=600&theme=dark"

Example Response

Returns an SVG image with Content-Type: image/svg+xml

chart.svg

<?xml version="1.0" encoding="UTF-8"?>
<svg width="800" height="400" xmlns="http://www.w3.org/2000/svg">
  <!-- Chart content -->
</svg>

Access Control

• Public Servers: Charts are accessible to anyone with the server ID
• Private Servers: Requires authentication - you must be logged in as the server owner

Tip

For private servers, include your session cookie in the request. The API will verify that you own the server before returning the chart.

Usage Examples

HTML Embed

Embed the chart directly in an HTML page:

embed.html

<img
  src="https://api.statsly.org/api/servers/your-server-id/chart/players?days=7&theme=light"
  alt="Server Statistics"
  width="800"
  height="400"
/>

Discord Bot

Use the chart URL in Discord embeds:

discord.js

const chartUrl = `https://api.statsly.org/api/servers/${serverId}/chart/players?days=7&theme=dark`;

const embed = new EmbedBuilder()
  .setTitle('Server Statistics')
  .setImage(chartUrl)
  .setTimestamp();

await channel.send({ embeds: [embed] });

Markdown/README

Use the chart URL in Markdown files:

readme.md

![Server Statistics](https://api.statsly.org/api/servers/your-server-id/chart/players?days=30&width=1000&height=500)

Chart Features

Data Visualization

The chart displays two lines:

• Peak Players (blue line) - Maximum concurrent players for each time period
• Average Players (green line) - Average player count for each time period

Visual Elements

• Grid lines for easy reading
• Data points marked with circles
• Gradient area fills under the lines
• Y-axis labels showing player counts
• X-axis labels showing dates
• Legend identifying each line

Themes

Light Theme

• White background
• Dark text and grid lines
• Blue peak line, green average line

Dark Theme

• Dark background (#1a1a1a)
• Light text and grid lines
• Bright blue peak line, bright green average line

Note

Choose the theme that best matches your website or application’s design. Dark theme is perfect for dark mode interfaces, while light theme works well for traditional websites.

Best Practices

Caching

Charts are cached for 5 minutes to improve performance. If you need real-time data, consider:

• Using shorter cache times for your use case
• Implementing client-side caching
• Refreshing charts periodically

Performance

• Use appropriate dimensions - larger charts take longer to generate
• Limit date ranges for faster responses
• Consider caching charts on your end for frequently accessed data

Tip

For best performance, use dimensions between 800x400 and 1200x600. Date ranges of 7-30 days provide a good balance between detail and load time.

Error Handling

The API returns appropriate HTTP status codes:

• 200 - Success (SVG chart returned)
• 400 - Bad Request (invalid parameters)
• 403 - Forbidden (private server, not authenticated)
• 404 - Not Found (server doesn’t exist)
• 500 - Internal Server Error

error-handling.js

try {
  const response = await fetch(chartUrl);

  if (!response.ok) {
    if (response.status === 403) {
      console.error('Access denied - server is private');
    } else if (response.status === 404) {
      console.error('Server not found');
    } else {
      console.error('Failed to load chart');
    }
    return;
  }

  const svg = await response.text();
  // Use the SVG
} catch (error) {
  console.error('Network error:', error);
}

Parameter Validation

All parameters are validated:

• days: Must be between 1 and 365
• width: Must be between 200 and 2000 pixels
• height: Must be between 200 and 2000 pixels
• theme: Must be either light or dark

Invalid parameters will return a 400 Bad Request response with an error message.

Example Endpoints

Test/Example Chart

For testing purposes, you can use the example endpoint:

Endpoint: GET /api/charts/example

This endpoint generates a chart with fake data, useful for testing your integration without needing a real server.

example

curl "https://api.statsly.org/api/charts/example?days=7&width=800&height=400&theme=light"

Rate Limiting

Charts are subject to rate limiting to ensure fair usage:

• Public endpoints: 100 requests per 15 minutes per IP
• Private endpoints: No rate limiting (IP whitelist only)

Caution

If you exceed rate limits, you’ll receive a 429 Too Many Requests response. Implement exponential backoff in your application.

Support

For questions or issues with the Image API:

• Open a support ticket
• Join our Discord community