SDKs overview

Pixela offers an open-source API designed for personal habit tracking and custom metric logging, allowing users to create and visualize data graphs programmatically. While the core API is accessible via standard HTTP requests, Software Development Kits (SDKs) and community-contributed libraries simplify interaction by providing language-specific abstractions. These tools streamline common tasks such as user registration, graph creation, and posting pixel data, reducing the need for direct HTTP request construction and JSON parsing.

The primary method for interacting with Pixela remains its RESTful API, which supports operations like user management, graph definition, and data point (pixel) manipulation. Developers can send HTTP requests using tools like cURL, or integrate the API through various programming languages by implementing HTTP clients. SDKs and libraries build upon this foundation, offering a more idiomatic experience for specific languages, handling authentication, request formatting, and response parsing internally.

This page details the official SDKs maintained by the Pixela project and highlights notable community-driven libraries that extend Pixela's reach into other programming ecosystems. Understanding the available tools helps developers choose the most efficient way to integrate Pixela's functionality into their applications, whether for personal dashboards, automation scripts, or custom data visualization projects.

Official SDKs by language

As of 2026, Pixela officially maintains one SDK. This SDK is developed and supported by the Pixela project team, ensuring compatibility with the latest API features and best practices. The official SDK aims to provide a reliable and comprehensive interface for developers working within its supported programming language.

Official Pixela SDKs
Language Package Name Install Command Maturity
Go github.com/a-know/go-pixela go get github.com/a-know/go-pixela Stable

Installation

Installing the official Pixela Go SDK involves using Go's standard package management tools. For community libraries, installation procedures vary based on the language's package manager.

Go SDK Installation

To install the official Pixela Go SDK, execute the following command in your terminal:

go get github.com/a-know/go-pixela

This command downloads the package and its dependencies, making it available for import in your Go projects. Once installed, you can import the library into your Go source files:

import (
    "github.com/a-know/go-pixela"
)

Community Library Installation Guidelines

For community-contributed libraries, installation typically follows the conventions of their respective programming languages:

  • Python: Often installed via pip (e.g., pip install pixela-python).
  • Ruby: Usually installed via gem (e.g., gem install pixela-ruby).
  • JavaScript/Node.js: Installed via npm or yarn (e.g., npm install pixela-js).

Always refer to the specific library's documentation, usually found on its repository (e.g., GitHub) or package manager page, for precise installation instructions and system requirements. Community libraries may have different dependency trees or setup procedures compared to official SDKs.

Quickstart example

This quickstart demonstrates how to use the official Pixela Go SDK to create a user, define a graph, and post a pixel. This example assumes you have the Go programming language installed and the go-pixela package installed as described in the installation section.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/a-know/go-pixela"
)

func main() {
	// Replace with your desired username and token
	username := os.Getenv("PIXELA_USERNAME")
	token := os.Getenv("PIXELA_TOKEN")

	// Initialize Pixela client
	client, err := pixela.New(
		username, 
		token, 
		true, // Use verbose output for debugging
	)
	if err != nil {
		fmt.Printf("Failed to create Pixela client: %v\n", err)
		return
	}

	ctx := context.Background()

	// 1. Create a user
	// This operation only needs to be performed once for a given username.
	// If the user already exists, Pixela will return an error.
	userCreateResp, err := client.PostUser(ctx, &pixela.PostUserOption{
		AgreeTermsOfService: "yes",
		NotMinor:            "yes",
	})
	if err != nil {
		// Check if the error indicates the user already exists
		if userCreateResp != nil && userCreateResp.IsSuccess == false && userCreateResp.Message == "This user already exist."{ 
			fmt.Println("User already exists, proceeding.")
		} else {
			fmt.Printf("Failed to create user: %v\n", err)
			return
		}
	} else {
		fmt.Printf("User creation success: %v\n", userCreateResp.IsSuccess)
	}

	// 2. Create a graph
	graphID := "coding-progress"
	graphName := "Coding Progress Graph"
	unit := "commit"
	graphColor := pixela.ColorShibafu // Green
	graphType := pixela.GraphTypeInt

	graphCreateResp, err := client.PostGraph(ctx, 
		graphID,
		graphName,
		unit,
		graphColor,
		graphType,
		&pixela.PostGraphOption{},
	)
	if err != nil {
		// Similar check for graph existence
		if graphCreateResp != nil && graphCreateResp.IsSuccess == false && graphCreateResp.Message == "This graph already exist."{ 
			fmt.Println("Graph already exists, proceeding.")
		} else {
			fmt.Printf("Failed to create graph: %v\n", err)
			return
		}
	} else {
		fmt.Printf("Graph creation success: %v\n", graphCreateResp.IsSuccess)
	}

	// 3. Post a pixel (increment value for today)
	date := pixela.Today().Format("20060102") // YYYYMMDD format
	value := "5" // Example value

	pixelPostResp, err := client.PostPixel(ctx, graphID, date, value, nil)
	if err != nil {
		fmt.Printf("Failed to post pixel: %v\n", err)
		return
	}
	fmt.Printf("Pixel post success: %v\n", pixelPostResp.IsSuccess)

	fmt.Printf("\nView your graph at: %s\n", client.GetGraphURL(graphID))
}

Before running this code:

  1. Set your Pixela username and API token as environment variables: PIXELA_USERNAME and PIXELA_TOKEN.
  2. Ensure your firewall or network configuration allows outbound HTTPS connections to pixe.la.

Community libraries

Beyond the official Go SDK, the Pixela community has developed several third-party libraries across various programming languages. These libraries are typically open-source and maintained independently by their creators. While not officially supported by the Pixela project, they offer developers more options for integrating Pixela into their preferred environments.

When considering a community library, it is advisable to check its documentation, the activity of its maintainers, and its compatibility with the latest Pixela API version. Important factors include:

  • Maturity and maintenance: How frequently is the library updated? Are issues addressed promptly?
  • Feature completeness: Does it support all the Pixela API endpoints you need?
  • Documentation and examples: Is it easy to understand and use?
  • License: Is the license compatible with your project's requirements?

Some examples of community-contributed libraries that have been noted include implementations for Python, Ruby, and JavaScript. These libraries typically wrap the Pixela REST API, providing a more object-oriented or functional interface tailored to the language's conventions. Developers should consult public code repositories like GitHub for the most up-to-date list and status of these community-driven projects. For example, a search for pixela python or pixela javascript on GitHub often yields relevant results.

Using a community library can accelerate development by providing pre-built functions for API interactions, handling serialization/deserialization of JSON payloads, and managing HTTP requests. However, developers assume responsibility for monitoring updates and potential breaking changes in these third-party integrations.