Image-Charts Getting Started: Quickstart Guide (2026)

Getting started overview

This guide provides a focused overview for getting started with Image-Charts, covering account creation, understanding authentication, and making your first API request. Image-Charts generates static image charts based on parameters embedded in a URL, making it suitable for contexts like emails, PDFs, or server-side rendering where dynamic client-side charting is not feasible or desired. The service supports various chart types, including line, bar, pie, and scatter charts, configured through URL query parameters.

The core interaction with Image-Charts involves constructing a URL with specific parameters that define the chart's data, type, size, colors, and labels. When this URL is accessed, Image-Charts renders and returns the chart as an image file (e.g., PNG, SVG). No dedicated SDKs are provided; instead, developers interact directly with the API via HTTP requests. The Image-Charts documentation provides a comprehensive API reference detailing all available parameters and their usage.

Before making requests, it is beneficial to review the Image-Charts documentation to understand the various chart types and customization options available. The process generally involves:

1. Account Creation: Registering for an Image-Charts account.
2. API Keys (Optional): Understanding when and how to obtain and use an API key.
3. Constructing a Request: Building a URL with the necessary chart parameters.
4. Making the Call: Accessing the constructed URL to retrieve the chart image.

The following table summarizes the initial steps:

Create an account and get keys

Image-Charts offers a free tier that allows up to 100 charts per month without requiring an API key for basic usage. For higher volumes or advanced features, a paid subscription is necessary, which typically involves obtaining an API key. An API key, when required, is used to authenticate requests and associate them with your account and subscription limits.

To create an account:

1. Navigate to the Image-Charts pricing page.
2. Select a plan, including the free tier option, and follow the registration prompts. This typically involves providing an email address and creating a password.
3. Once registered, you will gain access to your account dashboard.

For most initial explorations and free-tier usage, an API key is not strictly required. Image-Charts primarily relies on URL parameters for defining chart properties, and the service often functions without explicit authentication for basic requests. However, for features such as custom branding, higher rate limits, or specific paid plan benefits, an API key might be necessary. If an API key is needed, it will be available in your Image-Charts account dashboard after subscribing to a paid plan.

When an API key is provided, it is typically included as a query parameter in the chart URL, for example, &ichart&secret=YOUR_API_KEY. Refer to the Image-Charts Authentication documentation for specific instructions on integrating your API key into requests if your use case requires it.

Your first request

Making your first request to Image-Charts involves constructing a URL with the desired chart parameters. The base URL for the Image-Charts API is https://image-charts.com/chart. All chart configurations are appended to this base URL as query parameters.

Let's create a simple bar chart. The essential parameters for a basic chart include:

• cht: Chart type (e.g., bvg for vertical bar chart).
• chd: Chart data (e.g., a:60,40,20 for three data points).
• chs: Chart size (e.g., 300x200 for 300 pixels wide by 200 pixels high).
• chl: Chart labels (e.g., A|B|C for labels for each bar).

Consider the following example for a vertical bar chart:

https://image-charts.com/chart?cht=bvg&chd=a:60,40,20&chs=300x200&chl=Apples|Bananas|Oranges

To make this request, you can simply paste the URL into your web browser's address bar. The browser will then display the generated chart image. Alternatively, you can use a command-line tool like curl:

curl "https://image-charts.com/chart?cht=bvg&chd=a:60,40,20&chs=300x200&chl=Apples|Bananas|Oranges" > first_chart.png

This curl command fetches the chart image and saves it as first_chart.png in your current directory.

For programmatic integration, you can use any HTTP client library in your preferred programming language. Here are examples in JavaScript and Python:

JavaScript Example (Node.js using node-fetch)

const fetch = require('node-fetch');
const fs = require('fs');

async function generateChart() {
  const chartUrl = "https://image-charts.com/chart?cht=bvg&chd=a:60,40,20&chs=300x200&chl=Apples|Bananas|Oranges";
  try {
    const response = await fetch(chartUrl);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const buffer = await response.buffer();
    fs.writeFileSync('first_chart_js.png', buffer);
    console.log('Chart generated and saved as first_chart_js.png');
  } catch (error) {
    console.error('Error generating chart:', error);
  }
}

generateChart();

Python Example (using requests library)

import requests

def generate_chart():
    chart_url = "https://image-charts.com/chart?cht=bvg&chd=a:60,40,20&chs=300x200&chl=Apples|Bananas|Oranges"
    try:
        response = requests.get(chart_url, stream=True)
        response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
        with open('first_chart_py.png', 'wb') as out_file:
            for chunk in response.iter_content(chunk_size=8192):
                out_file.write(chunk)
        print('Chart generated and saved as first_chart_py.png')
    except requests.exceptions.RequestException as e:
        print(f"Error generating chart: {e}")

if __name__ == "__main__":
    generate_chart()

These examples demonstrate how to construct the URL and fetch the image programmatically. For more complex charts or to explore other chart types and customization options, consult the Image-Charts documentation, which provides detailed parameter explanations and examples.

Common next steps

After successfully generating your first chart, consider these common next steps to further integrate and optimize your Image-Charts usage:

• Explore Chart Types: Image-Charts supports various chart types beyond simple bar charts, including line charts (lc), pie charts (p), scatter charts (s), and QR codes (qr). Experiment with different cht parameter values to find the best visualization for your data. The Image-Charts API reference lists all supported types.
• Data Formatting: Understand the different data formatting options available (chd parameter). Image-Charts supports simple text encoding, extended encoding, and custom scaling to handle diverse data ranges and precision requirements. For example, chd=t:10,20,30 uses text encoding.
• Customization Options: Image-Charts offers extensive customization for colors (chco), labels (chl, chxl), axis ranges (chxr), titles (chtt), and backgrounds (chf). These parameters allow you to tailor charts to match your application's aesthetic. For instance, chco=FF0000,00FF00 sets red and green colors for bars.
• Error Handling: Implement robust error handling in your applications. While Image-Charts typically returns an image, incorrect parameters might lead to an invalid or empty image, or an HTTP error status code. Monitor HTTP status codes and check for expected image content.
• Dynamic Chart Generation: Integrate chart generation into your application's backend. Instead of hardcoding URLs, dynamically construct chart URLs based on user input or real-time data from a database.
• Security Considerations: If you are exposing chart URLs directly to users, be mindful of URL length limitations and potential for URL manipulation. While Image-Charts primarily renders visual data, ensuring data privacy and integrity is important. For sensitive data, consider generating charts server-side and serving the images securely. This aligns with general web security best practices for URLs.
• Caching: Image-Charts URLs can be quite long and complex. To improve performance and reduce redundant requests, implement caching strategies for generated chart images, either on your server or client-side.
• Paid Plans and API Keys: If your usage exceeds the free tier or requires features like custom branding, consider upgrading to a paid plan. Familiarize yourself with how to manage and use your API key (Image-Charts API Key documentation) for authenticated requests.
• Explore the Playground: The Image-Charts Playground is an interactive tool where you can build charts visually and see the corresponding URL generated in real-time. This is useful for prototyping and understanding parameter effects.

Troubleshooting the first call

When encountering issues with your first Image-Charts request, consider the following common troubleshooting steps:

• URL Syntax Errors: The most frequent issue is incorrect URL parameter syntax. Ensure all parameters are correctly formatted (e.g., param=value), separated by &, and that values are properly URL-encoded, especially if they contain special characters or spaces. For example, spaces in labels like chdl=My Data should be chdl=My%20Data.
• Missing Required Parameters: All charts require at least a chart type (cht), data (chd), and size (chs). Verify that these fundamental parameters are present in your URL. Without them, the API cannot generate a valid chart.
• Invalid Parameter Values: Check if the values provided for parameters are within the expected range or format. For example, chart size (chs) expects dimensions like WIDTHxHEIGHT (e.g., 300x200), not just a single number. Data values (chd) should typically be numerical.
• Network Connectivity: Ensure your application or browser has a stable internet connection and can reach https://image-charts.com. Network issues can prevent the image from being fetched.
• HTTP Status Codes: If using a programmatic approach (e.g., curl, requests), check the HTTP status code returned by the API. A 200 OK indicates success. Other codes, like 400 Bad Request, suggest an issue with your request parameters, while 5xx codes indicate server-side problems.
• Image Content Verification: If the request appears successful but no image is displayed or saved, verify the content type of the response. It should be an image type (e.g., image/png). If the content type is text/html or application/json, it might indicate an error message from the API.
• API Key Issues (if applicable): If you are using an API key and experiencing issues, ensure it is correctly included in the URL (e.g., &ichart&secret=YOUR_KEY) and that it is active and not expired. Verify your subscription status on your Image-Charts dashboard.
• Browser Caching: Sometimes, browsers might cache an old, incorrect chart image. Try clearing your browser cache or performing a hard refresh (Ctrl+F5 or Cmd+Shift+R) when testing in a browser.
• Consult Documentation and Playground: Use the Image-Charts Playground to build your desired chart visually and compare the generated URL with your own. This can help identify subtle parameter discrepancies. Refer to the official Image-Charts documentation for detailed explanations of each parameter.