chartquery

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2026 License: MIT Imports: 18 Imported by: 0

README

ChartQuery Go SDK

The official Go SDK for the ChartQuery chart and QR code API.

Generate chart images, diagrams, barcodes, QR codes and thermal labels on demand. PNG, SVG or PDF output.

The SDK exposes 20 typed methods, one per documented endpoint, plus a generic Request(). It has no dependencies outside the standard library.

Requirements

  • Go 1.22 or newer

Installation

go get github.com/chartquery/chartquery-go

Get your API key

Sign up for ChartQuery or sign in, then copy your API key from the dashboard. NewClient("", nil) reads the CHARTQUERY_API_KEY environment variable.

Quick start

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/chartquery/chartquery-go"
)

func main() {
	client, err := chartquery.NewClient("", nil) // reads CHARTQUERY_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()
	response, err := client.ChartAI(ctx, &chartquery.ChartAIParams{Prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18"})
	if err != nil {
		log.Fatal(err)
	}
	data, err := response.Map()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(data)
}

Parameter structs mirror the API reference. Required fields are plain values; optional fields are pointers — use chartquery.String, chartquery.Float, chartquery.Int and chartquery.Bool.

Decode into your own types with response.Decode(&value).

Binary responses

Endpoints that return a file (image, PDF…) give you the bytes in Body; IsJSON tells both cases apart:

response, err := client.Qrcode(ctx, &chartquery.QrcodeParams{Data: "https://chartquery.com", Format: chartquery.String("png")})
if err != nil {
	log.Fatal(err)
}
if !response.IsJSON {
	err = os.WriteFile("qrcode.png", response.Body, 0o644)
}

Async jobs

Any call accepts is_async: true (useful past the 60-second server limit): the response is then a job_id. WaitForJob polls GET /v1/jobs/{id} until a terminal status (CompletedJob, Error, NotFound, BadRequest):

submitted, err := client.ChartAI(ctx, &chartquery.ChartAIParams{Prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18", IsAsync: chartquery.Bool(true)})
if err != nil {
	log.Fatal(err)
}
var accepted struct{ JobID string `json:"job_id"` }
if err := submitted.Decode(&accepted); err != nil {
	log.Fatal(err)
}
job, err := client.WaitForJob(ctx, accepted.JobID, &chartquery.WaitForJobOptions{
	OnProgress: func(job map[string]any) { fmt.Println(job["status"], job["progress"]) },
})

GET or POST

Methods use GET when the endpoint supports it (parameters in the query string); WithMethod("POST") sends them as a JSON body.

response, err := client.Barcode(ctx, &chartquery.BarcodeParams{Data: "test"}, chartquery.WithMethod("POST"))

Any endpoint

response, err := client.Request(ctx, "GET", "/v1/usage", nil)

Errors

response, err := client.ChartAI(ctx, &chartquery.ChartAIParams{Prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18"})
if apiError, ok := chartquery.IsAPIError(err); ok {
	log.Printf("HTTP %d: %s", apiError.StatusCode, apiError.Message)
}
Error When
*ConfigurationError Missing API key, invalid options or unsupported method.
*SerializationError A required parameter is missing or a value can't be sent.
*TransportError Network failure, timeout or cancelled context (errors.Is(err, context.DeadlineExceeded)).
*APIError Non-2xx status (StatusCode, Message, Response).
*ResponseDecodingError A success response could not be decoded.

Retries

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a rate limit — which the API returns as 401 (or 429) with a Rate limit exceeded message. Per-key quota errors (…: quota daily) are not retried, nor are 400, 402, 404 or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a Retry-After header wins.

client, err := chartquery.NewClient("", &chartquery.ClientOptions{
	MaxRetries: 5,                      // negative disables retries
	RetryDelay: 500 * time.Millisecond,
})

// or for one request
response, err := client.ChartAI(ctx, &chartquery.ChartAIParams{Prompt: "Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18"}, chartquery.WithMaxRetries(0))

Batch requests

chartquery.Batch runs a function per item with at most 10 calls in flight and returns one BatchResult per item, in input order. A failing item never stops the others.

inputs := []string{"Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18", "Market share as a pie chart: A 40, B 35, C 25"}
results := chartquery.Batch(ctx, inputs, 5, func(ctx context.Context, value string) (*chartquery.Response, error) {
	return client.ChartAI(ctx, &chartquery.ChartAIParams{Prompt: value})
})
for _, result := range results {
	if result.Err != nil {
		log.Printf("%s: %v", inputs[result.Index], result.Err)
		continue
	}
	fmt.Println(string(result.Value.Body))
}
Constant Default Description
DefaultConcurrency 10 Tasks run at the same time by batch
DefaultTimeout 120 * time.Second Request timeout
MaxRetries 3 Retry attempts after a network error, a 408/5xx or a rate limit
RetryBackoffFactor 1.5 Exponential backoff multiplier
DefaultRetryDelay time.Second Delay before the first retry

Timeouts and custom HTTP clients

client, err := chartquery.NewClient("", &chartquery.ClientOptions{
	Timeout:    60 * time.Second, // default 120 s; negative disables
	HTTPClient: &http.Client{Transport: myTransport},
})

Every method also honours the deadline and cancellation of the context.Context you pass.

Endpoints

20 methods, generated from the OpenAPI document.

Method HTTP Description
Barcode GET / POST /v1/barcode Generate a barcode image via GET. Output: SVG (default) or PNG. Supports 25+ formats: EAN-13, Code 128, ITF-14, GS1-128, postal codes and m…
Chart GET / POST /v1/chart Render a Chart.js image via GET. Pass the full chart object as URL-encoded JSON in query. Prefer format png for ChatGPT. POST sends the sam…
ChartAI GET / POST /v1/chart/ai Describe a chart in plain English via GET and get a rendered image back. Powered by AI.
ChartRender GET /v1/chart/render/{id} Render a previously saved chart by ID. Public, no API key required. Supports URL overrides for templates (?data1=, ?labels=, ?title=…).
ChartView GET /v1/chart/view/{id} View a previously saved chart as an interactive HTML page. Public, no API key required. Iframe-embeddable.
Diagram GET / POST /v1/diagram Render a diagram via GET. Use type (mermaid, d2, …), query (source code), and format=png for ChatGPT. POST uses diagram_type and diagram_so…
DiagramAI GET / POST /v1/diagram/ai Describe a diagram in plain English via GET and get a rendered image back. Powered by AI.
DiagramRender GET /v1/diagram/render/{id} Render a previously saved diagram by ID. Public, no API key required. Supports ?format= and ?query= overrides.
DiagramView GET /v1/diagram/view/{id} View a previously saved diagram as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.
Jobs GET /v1/jobs/{id} Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: Completed…
Label GET / POST /v1/label Preview a thermal label via GET. Pass the same label object as a URL-encoded JSON string in query. Inside that JSON, text items use content…
LabelCompile POST /v1/label/compile Compile a label to printer commands (tsc, zpl, epl, …). POST width, language, and elements. Text uses content and size (1-10), not text or…
LabelConvert POST /v1/label/convert Convert printer commands from one language to another. POST source, from, and to. from is the source language (tsc, zpl, epl, …). to is the…
LabelParse POST /v1/label/parse Parse printer commands into structured elements. POST source and language (tsc, zpl, epl, …).
LabelRender GET /v1/label/render/{id} Render a previously saved label by ID. Public, no API key required. Supports ?format= override.
LabelValidate POST /v1/label/validate Validate printer commands. POST source (the raw commands) and language (tsc, zpl, epl, …).
LabelView GET /v1/label/view/{id} View a previously saved label as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.
Qrcode GET / POST /v1/qrcode Generate a styled QR code via GET. Output: SVG (default) or PNG. Supports dot styles, gradients, custom corners and all QR versions.
Stats GET /v1/stats Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea…
Usage GET /v1/usage Return this account's Chartquery usage and credit balance. No body. Requires an API key.

License

MIT — see LICENSE.

Documentation

Overview

Package chartquery is the official Go SDK for the ChartQuery API (https://www.chartquery.com).

Generate chart images, diagrams, barcodes, QR codes and thermal labels on demand. PNG, SVG or PDF output.

Create one client and reuse it: 

client, err := chartquery.NewClient("", nil) // reads CHARTQUERY_API_KEY
response, err := client.ChartAI(ctx, ...)

Every documented endpoint has a typed method; Client.Request reaches any other path.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the production API origin.
	DefaultBaseURL = "https://api.chartquery.com"
	// DefaultTimeout bounds every request unless ClientOptions.Timeout says otherwise.
	DefaultTimeout = 120 * time.Second
	// APIKeyEnvironmentVariable is read when NewClient receives an empty API key.
	APIKeyEnvironmentVariable = "CHARTQUERY_API_KEY"
	// DefaultConcurrency is the number of tasks Batch runs at the same time.
	DefaultConcurrency = 10
	// MaxRetries is the default number of retries after a network error or a 408, 429, 500, 502, 503 or 504.
	MaxRetries = 3
	// RetryBackoffFactor multiplies the delay before each new retry (a Retry-After header wins).
	RetryBackoffFactor = 1.5
	// DefaultRetryDelay is the delay before the first retry.
	DefaultRetryDelay = time.Second
	// MaxRetryDelay caps the delay between two attempts.
	MaxRetryDelay = 30 * time.Second
)
View Source 
const Version = "0.1.0"

Version is the SDK version sent in the User-Agent header.

Variables

View Source 
var JobTerminalStatuses = []string{"CompletedJob", "Error", "NotFound", "BadRequest"}

JobTerminalStatuses are the job statuses WaitForJob stops on.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a pointer to v, for optional boolean parameters.

func Float 

func Float(v float64) *float64

Float returns a pointer to v, for optional number parameters.

func Int 

func Int(v int64) *int64

Int returns a pointer to v, for optional integer parameters.

func String 

func String(v string) *string

String returns a pointer to v, for optional parameters.

Types

type APIError 

type APIError struct {
	StatusCode int
	// Message is the "error" (or "message") field of the JSON body, when present.
	Message  string
	Response *Response
}

APIError is returned for non-2xx responses.

func IsAPIError 

func IsAPIError(err error) (*APIError, bool)

IsAPIError reports whether err is an *APIError and returns it.

func (*APIError) Error 

func (e *APIError) Error() string

type BarcodeParams 

type BarcodeParams struct {
	// The data to encode in the barcode. Examples by type:
	Data string `json:"data" api:"data,required"`
	// Barcode format. Default: code128. Allowed values: code128, code39, code39ext, code93, code93ext, ean13, ean8, ean5, ean2, upca, upce, itf, itf14, codabar, msi, pharmacode, code11, gs1-128, gs1-databar, gs1-databar-limited…. Default: "code128".
	Type *string `json:"type" api:"type"`
	// Bar height in pixels. Default: 80. Typical values: 50 (compact), 80 (standard), 100–120 (tall labels). Example: ?height=100
	Height *float64 `json:"height" api:"height"`
	// Bar color as a CSS color string. Default: #000. Examples: ?color=%231e293b (dark slate), ?color=%230f172a (near black), ?color=%237c3aed (purple), ?color=%23dc2626 (red). Use %23 to URL-encode the # character.
	Color *string `json:"color" api:"color"`
	// Show human-readable text below the bars. Example: ?show_text=true. Combine with font_size and text_align for print labels.
	ShowText *bool `json:"show_text" api:"show_text"`
	// Position of the human-readable text label. Default: bottom. Example: ?text_position=top Allowed values: bottom, top. Default: "bottom".
	TextPosition *string `json:"text_position" api:"text_position"`
	// Horizontal alignment of the text label. Default: center. Example: ?text_align=left Allowed values: center, left, right. Default: "center".
	TextAlign *string `json:"text_align" api:"text_align"`
	// Font size of the text label in pixels. Default: 14. Example: ?font_size=12
	FontSize *float64 `json:"font_size" api:"font_size"`
	// Font family of the text label. Default: monospace. Examples: ?font_family=monospace, ?font_family=sans-serif, ?font_family=Arial
	FontFamily *string `json:"font_family" api:"font_family"`
	// Width multiplier per module (bar). Default: 2. Increase for wider, more scannable barcodes. Example: ?bar_width=3
	BarWidth *float64 `json:"bar_width" api:"bar_width"`
	// Extra horizontal spacing between bars in pixels. Default: 0. Example: ?bar_gap=1
	BarGap *float64 `json:"bar_gap" api:"bar_gap"`
	// Background fill color. Default: #fff. Use transparent for no background. Example: ?background=%23f8fafc
	Background *string `json:"background" api:"background"`
	// Uniform margin around the barcode in pixels. Default: 10. Overridden per side by margin_top/bottom/left/right. Example: ?margin=6
	Margin *float64 `json:"margin" api:"margin"`
	// Top margin in pixels (overrides margin). Example: ?margin_top=4
	MarginTop *float64 `json:"margin_top" api:"margin_top"`
	// Bottom margin in pixels (overrides margin). Example: ?margin_bottom=4
	MarginBottom *float64 `json:"margin_bottom" api:"margin_bottom"`
	// Left margin in pixels (overrides margin). Example: ?margin_left=8
	MarginLeft *float64 `json:"margin_left" api:"margin_left"`
	// Right margin in pixels (overrides margin). Example: ?margin_right=8
	MarginRight *float64 `json:"margin_right" api:"margin_right"`
	// Rotate the barcode by 0, 90, 180 or 270 degrees. Default: 0. Use 90 or 270 for vertical label orientation. Example: ?rotation=90
	Rotation *float64 `json:"rotation" api:"rotation"`
	// Add horizontal bearer bars above and below the barcode. Required for ITF-14. Default: false. Example: ?bearer_bars=true
	BearerBars *bool `json:"bearer_bars" api:"bearer_bars"`
	// Measurement unit for dimensions. Default: px. Use mm, in or cm for print-ready output. Example: ?unit=mm Allowed values: px, mm, in, cm. Default: "px".
	Unit *string `json:"unit" api:"unit"`
	// Accessible label added as aria-label on the SVG element. Improves screen reader support. Example: ?aria_label=EAN-13+barcode+for+product+4006381333931
	AriaLabel *string `json:"aria_label" api:"aria_label"`
	// SVG <title> element for tooltip and accessibility. Example: ?title=Product+Barcode
	Title *string `json:"title" api:"title"`
	// SVG <desc> element for extended accessibility description. Example: ?desc=EAN-13+encoding+GTIN+for+Nivea+cream+75ml
	Desc *string `json:"desc" api:"desc"`
	// Output format. Default: svg. Use png to get a raster image. SVG is lossless and scalable; PNG is pixel-based and suitable for email, PDF or messaging. Example: ?format=png Allowed values: svg, png. Default: "svg".
	Format *string `json:"format" api:"format"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

BarcodeParams holds the parameters of Barcode (GET / POST /v1/barcode). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type BatchResult 

type BatchResult[T any] struct {
	Index int
	Value T
	Err   error
}

BatchResult is the outcome of one Batch item.

func Batch 

func Batch[I, T any](ctx context.Context, items []I, concurrency int, task func(ctx context.Context, item I) (T, error)) []BatchResult[T]

Batch runs task for every item with at most concurrency calls in flight (DefaultConcurrency when concurrency <= 0) and returns one result per item, in input order. A failing item never stops the others; items not started when ctx is done get ctx.Err().

type ChartAIParams 

type ChartAIParams struct {
	// Describe your chart in plain English (max 1000 chars). Be specific: mention chart type, data topic, colors, style.
	Prompt string `json:"prompt" api:"prompt,required"`
	// Raw data for the chart. URL-encoded string, CSV, or JSON. AI will parse and structure it.
	RawData *string `json:"raw_data" api:"raw_data"`
	// Override the chart title generated by AI.
	Title *string `json:"title" api:"title"`
	// Override the chart subtitle.
	Subtitle *string `json:"subtitle" api:"subtitle"`
	// Legend position or visibility. Use "false" to hide. Allowed values: top, bottom, left, right, chartArea, false. Default: "top".
	Legend *string `json:"legend" api:"legend"`
	// Output format. Default: "png". Allowed values: png, svg. Default: "png".
	Format *string `json:"format" api:"format"`
	// Image width in pixels (50–4000). Default: 1200.
	Width *float64 `json:"width" api:"width"`
	// Image height in pixels (50–4000). Default: 600.
	Height *float64 `json:"height" api:"height"`
	// Background color as a hex value. Default: #ffffff.
	Background *string `json:"background" api:"background"`
	// Device pixel ratio for the rendered image. Default: 1.
	DevicePixelRatio *float64 `json:"device_pixel_ratio" api:"device_pixel_ratio"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

ChartAIParams holds the parameters of ChartAI (GET / POST /v1/chart/ai). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type ChartParams 

type ChartParams struct {
	// Full chart config as URL-encoded JSON. Pass ?version= or ?v= separately to pin the chart version.
	Query string `json:"query" api:"query,required"`
	// Chart.js version to use. Alias: ?v=. Only v4.x is supported. Defaults to the installed version (4.5.1). Example: "4", "4.5", "4.5.1". The installed version is always returned in the X-ChartJS-Version response header. Default: "4.5.1".
	Version *string `json:"version" api:"version"`
	// If true, persist the result and return share URLs instead of an image. Leave false to get the image.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

ChartParams holds the parameters of Chart (GET / POST /v1/chart). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type ChartRenderParams 

type ChartRenderParams struct {
	// The chart ID returned in the X-Chart-Render-URL header when saving a chart. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
	ID string `json:"id" api:"id,required"`
	// Override the chart title.
	Title *string `json:"title" api:"title"`
	// Override X-axis labels. Comma-separated.
	Labels *string `json:"labels" api:"labels"`
	// Override first dataset values. Comma-separated numbers. Use data2, data3… for additional datasets.
	Data1 *string `json:"data1" api:"data1"`
	// Override output width in pixels (50–4000).
	Width *string `json:"width" api:"width"`
	// Override output height in pixels (50–4000).
	Height *string `json:"height" api:"height"`
	// Override output format. Allowed values: png, svg. Default: "png".
	Format *string `json:"format" api:"format"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

ChartRenderParams holds the parameters of ChartRender (GET /v1/chart/render/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type ChartViewParams 

type ChartViewParams struct {
	// The chart ID returned in the X-Chart-View-URL header when saving a chart. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
	ID string `json:"id" api:"id,required"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

ChartViewParams holds the parameters of ChartView (GET /v1/chart/view/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a reusable, concurrency-safe ChartQuery API client.

func NewClient 

func NewClient(apiKey string, options *ClientOptions) (*Client, error)

NewClient creates a client. An empty apiKey falls back to the CHARTQUERY_API_KEY environment variable.

func (*Client) Barcode 

func (c *Client) Barcode(ctx context.Context, params *BarcodeParams, options ...RequestOption) (*Response, error)

Barcode — Barcode. Generate a barcode image via GET. Output: SVG (default) or PNG. Supports 25+ formats: EAN-13, Code 128, ITF-14, GS1-128, postal codes and more. Credit cost: 3 credits per call.

GET / POST /v1/barcode

func (*Client) Chart 

func (c *Client) Chart(ctx context.Context, params *ChartParams, options ...RequestOption) (*Response, error)

Chart — Chart. Render a Chart.js image via GET. Pass the full chart object as URL-encoded JSON in query. Prefer format png for ChatGPT. POST sends the same object as a JSON body, not query. Credit cost: 5 credits per call.

GET / POST /v1/chart

func (*Client) ChartAI 

func (c *Client) ChartAI(ctx context.Context, params *ChartAIParams, options ...RequestOption) (*Response, error)

ChartAI — Chart AI. Describe a chart in plain English via GET and get a rendered image back. Powered by AI. Credit cost: 10 credits per call.

GET / POST /v1/chart/ai

func (*Client) ChartRender 

func (c *Client) ChartRender(ctx context.Context, params *ChartRenderParams, options ...RequestOption) (*Response, error)

ChartRender — Chart Render. Render a previously saved chart by ID. Public, no API key required. Supports URL overrides for templates (?data1=, ?labels=, ?title=…).

GET /v1/chart/render/{id}

func (*Client) ChartView 

func (c *Client) ChartView(ctx context.Context, params *ChartViewParams, options ...RequestOption) (*Response, error)

ChartView — Chart View. View a previously saved chart as an interactive HTML page. Public, no API key required. Iframe-embeddable.

GET /v1/chart/view/{id}

func (*Client) Diagram 

func (c *Client) Diagram(ctx context.Context, params *DiagramParams, options ...RequestOption) (*Response, error)

Diagram — Diagram. Render a diagram via GET. Use type (mermaid, d2, …), query (source code), and format=png for ChatGPT. POST uses diagram_type and diagram_source instead. Credit cost: 5 credits per call.

GET / POST /v1/diagram

func (*Client) DiagramAI 

func (c *Client) DiagramAI(ctx context.Context, params *DiagramAIParams, options ...RequestOption) (*Response, error)

DiagramAI — Diagram AI. Describe a diagram in plain English via GET and get a rendered image back. Powered by AI. Credit cost: 10 credits per call.

GET / POST /v1/diagram/ai

func (*Client) DiagramRender 

func (c *Client) DiagramRender(ctx context.Context, params *DiagramRenderParams, options ...RequestOption) (*Response, error)

DiagramRender — Diagram Render. Render a previously saved diagram by ID. Public, no API key required. Supports ?format= and ?query= overrides.

GET /v1/diagram/render/{id}

func (*Client) DiagramView 

func (c *Client) DiagramView(ctx context.Context, params *DiagramViewParams, options ...RequestOption) (*Response, error)

DiagramView — Diagram View. View a previously saved diagram as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.

GET /v1/diagram/view/{id}

func (*Client) Jobs 

func (c *Client) Jobs(ctx context.Context, params *JobsParams, options ...RequestOption) (*Response, error)

Jobs — Jobs. Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: CompletedJob, Error, NotFound or BadRequest.

GET /v1/jobs/{id}

func (*Client) Label 

func (c *Client) Label(ctx context.Context, params *LabelParams, options ...RequestOption) (*Response, error)

Label — Label Preview. Preview a thermal label via GET. Pass the same label object as a URL-encoded JSON string in query. Inside that JSON, text items use content and size (1-10), not text or fontSize. Prefer format=png for ChatGPT. Credit cost: 3 credits per call.

GET / POST /v1/label

func (*Client) LabelCompile 

func (c *Client) LabelCompile(ctx context.Context, params *LabelCompileParams, options ...RequestOption) (*Response, error)

LabelCompile — Label Compile. Compile a label to printer commands (tsc, zpl, epl, …). POST width, language, and elements. Text uses content and size (1-10), not text or fontSize. No barcode element. Example: {"width":40,"height":30,"unit":"mm","language":"zpl","element… Credit cost: 3 credits per call.

POST /v1/label/compile

func (*Client) LabelConvert 

func (c *Client) LabelConvert(ctx context.Context, params *LabelConvertParams, options ...RequestOption) (*Response, error)

LabelConvert — Label Convert. Convert printer commands from one language to another. POST source, from, and to. from is the source language (tsc, zpl, epl, …). to is the target (tsc, zpl, escpos, …). Credit cost: 5 credits per call.

POST /v1/label/convert

func (*Client) LabelParse 

func (c *Client) LabelParse(ctx context.Context, params *LabelParseParams, options ...RequestOption) (*Response, error)

LabelParse — Label Parse. Parse printer commands into structured elements. POST source and language (tsc, zpl, epl, …). Credit cost: 1 credit per call.

POST /v1/label/parse

func (*Client) LabelRender 

func (c *Client) LabelRender(ctx context.Context, params *LabelRenderParams, options ...RequestOption) (*Response, error)

LabelRender — Label Render. Render a previously saved label by ID. Public, no API key required. Supports ?format= override.

GET /v1/label/render/{id}

func (*Client) LabelValidate 

func (c *Client) LabelValidate(ctx context.Context, params *LabelValidateParams, options ...RequestOption) (*Response, error)

LabelValidate — Label Validate. Validate printer commands. POST source (the raw commands) and language (tsc, zpl, epl, …). Credit cost: 1 credit per call.

POST /v1/label/validate

func (*Client) LabelView 

func (c *Client) LabelView(ctx context.Context, params *LabelViewParams, options ...RequestOption) (*Response, error)

LabelView — Label View. View a previously saved label as an HTML page. Public, no API key required. Iframe-embeddable with inline SVG rendering.

GET /v1/label/view/{id}

func (*Client) Qrcode 

func (c *Client) Qrcode(ctx context.Context, params *QrcodeParams, options ...RequestOption) (*Response, error)

Qrcode — QR Code. Generate a styled QR code via GET. Output: SVG (default) or PNG. Supports dot styles, gradients, custom corners and all QR versions. Credit cost: 3 credits per call.

GET / POST /v1/qrcode

func (*Client) Request 

func (c *Client) Request(ctx context.Context, method, path string, params map[string]any, options ...RequestOption) (*Response, error)

Request sends any request, including endpoints released after this SDK version. GET parameters travel in the query string; POST parameters travel in a JSON body.

func (*Client) Stats 

func (c *Client) Stats(ctx context.Context, params *StatsParams, options ...RequestOption) (*Response, error)

Stats — Stats. Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.

GET /v1/stats

func (*Client) Usage 

func (c *Client) Usage(ctx context.Context, options ...RequestOption) (*Response, error)

Usage — Usage. Return this account's Chartquery usage and credit balance. No body. Requires an API key.

GET /v1/usage

func (*Client) WaitForJob 

func (c *Client) WaitForJob(ctx context.Context, jobID string, options *WaitForJobOptions) (*Response, error)

WaitForJob polls GET /v1/jobs/{id} until the job reaches a terminal status and returns the last response.

type ClientOptions 

type ClientOptions struct {
	// BaseURL overrides DefaultBaseURL.
	BaseURL string
	// Timeout bounds each request. Zero uses DefaultTimeout; a negative value disables it.
	Timeout time.Duration
	// HTTPClient is copied and used for requests. Redirects are never followed.
	HTTPClient *http.Client
	// Headers are sent with every request.
	Headers map[string]string
	// MaxRetries overrides the number of retries. Zero uses MaxRetries; a negative value disables retries.
	MaxRetries int
	// RetryDelay is the delay before the first retry. Zero uses DefaultRetryDelay.
	RetryDelay time.Duration
}

ClientOptions configures a Client. The zero value is valid.

type ConfigurationError 

type ConfigurationError struct {
	Message string
	Err     error
}

ConfigurationError reports a missing or unusable client configuration.

func (*ConfigurationError) Error 

func (e *ConfigurationError) Error() string

func (*ConfigurationError) Unwrap 

func (e *ConfigurationError) Unwrap() error

type DiagramAIParams 

type DiagramAIParams struct {
	// Describe your diagram in plain English (max 1000 chars). Be specific: mention the diagram type, key entities, and relationships.
	Prompt string `json:"prompt" api:"prompt,required"`
	// Preferred diagram language. AI chooses if omitted. Examples: "mermaid", "d2", "plantuml", "graphviz". Allowed values: mermaid, d2, plantuml, graphviz. Default: "mermaid".
	DiagramType *string `json:"diagram_type" api:"diagram_type"`
	// Output format. Default: "svg". Allowed values: svg, png, jpeg, pdf. Default: "svg".
	OutputFormat *string `json:"output_format" api:"output_format"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry. Paid plan: 6-month expiry. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

DiagramAIParams holds the parameters of DiagramAI (GET / POST /v1/diagram/ai). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type DiagramParams 

type DiagramParams struct {
	// Diagram language. Allowed values: mermaid, graphviz, plantuml, d2, svgbob, nomnoml, blockdiag, seqdiag, actdiag, nwdiag, bpmn, erd, excalidraw, ditaa, vega, vegalite, wavedrom, wireviz, c4plantuml, structurizr…. Default: "mermaid".
	Type string `json:"type" api:"type,required"`
	// Diagram source code (URL-encoded).
	Query string `json:"query" api:"query,required"`
	// Use png so ChatGPT can display the image. svg is for download or infinite scale. Allowed values: svg, png, jpeg, pdf. Default: "svg".
	Format *string `json:"format" api:"format"`
	// If true, persist the result and return share URLs instead of an image. Leave false to get the image.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

DiagramParams holds the parameters of Diagram (GET / POST /v1/diagram). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type DiagramRenderParams 

type DiagramRenderParams struct {
	// The diagram ID returned in the X-Diagram-Render-URL header when saving a diagram. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
	ID string `json:"id" api:"id,required"`
	// Override output format. Allowed values: svg, png, jpeg, pdf. Default: "svg".
	Format *string `json:"format" api:"format"`
	// Override the diagram source code (URL-encoded).
	Query *string `json:"query" api:"query"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

DiagramRenderParams holds the parameters of DiagramRender (GET /v1/diagram/render/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type DiagramViewParams 

type DiagramViewParams struct {
	// The diagram ID returned in the X-Diagram-View-URL header when saving a diagram. Format: cq-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
	ID string `json:"id" api:"id,required"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

DiagramViewParams holds the parameters of DiagramView (GET /v1/diagram/view/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type JobTimeoutError 

type JobTimeoutError struct {
	JobID        string
	LastResponse *Response
}

JobTimeoutError reports an async job that did not finish before the deadline.

func (*JobTimeoutError) Error 

func (e *JobTimeoutError) Error() string

type JobsParams 

type JobsParams struct {
	// The job_id returned by an endpoint called with is_async=true.
	ID string `json:"id" api:"id,required"`
}

JobsParams holds the parameters of Jobs (GET /v1/jobs/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelCompileParams 

type LabelCompileParams struct {
	// Label width. Required. Default unit is mm. Example: 40. Do not send query instead of width.
	Width float64 `json:"width" api:"width,required"`
	// Label height in the same unit. Example: 30. Omit for receipt / continuous mode.
	Height *float64 `json:"height" api:"height"`
	// Measurement unit for width and height. Default mm. Use mm unless you are working in printer dots. Allowed values: mm, inch, dot. Default: "mm".
	Unit *string `json:"unit" api:"unit"`
	// Printer DPI. Default 203.
	DPI *float64 `json:"dpi" api:"dpi"`
	// Gap between labels in mm. Ignored for receipts.
	Gap *float64 `json:"gap" api:"gap"`
	// Print speed, 1-18.
	Speed *float64 `json:"speed" api:"speed"`
	// Print darkness, 0-15.
	Density *float64 `json:"density" api:"density"`
	// Print direction. 0 = normal, 1 = reversed. Default: 1.
	Direction *float64 `json:"direction" api:"direction"`
	// Number of copies. Minimum 1.
	Copies *float64 `json:"copies" api:"copies"`
	// Printer profile id (tsc-te210, zebra-zd420, …).
	Printer *string `json:"printer" api:"printer"`
	// Required array. Text items need type=text, content, and size (1-10 magnification). Do not use text, fontSize, or type=barcode. Positions x/y are in dots. Example item: {"type":"text","content":"Order: 1042","x":10,"y":10,"size":2}.
	Elements []map[string]any `json:"elements" api:"elements,required"`
	// Required printer language. Example: zpl or tsc. Do not omit. Allowed values: tsc, zpl, epl, cpcl, dpl, sbpl, escpos, starprnt, ipl. Default: "tsc".
	Language string `json:"language" api:"language,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelCompileParams holds the parameters of LabelCompile (POST /v1/label/compile). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelConvertParams 

type LabelConvertParams struct {
	// Raw printer commands to convert. Also send from and to.
	Source string `json:"source" api:"source,required"`
	// Source language. Allowed values: tsc, zpl, epl, cpcl, dpl, sbpl, ipl. Default: "tsc".
	From string `json:"from" api:"from,required"`
	// Target language. Allowed values: tsc, zpl, epl, cpcl, dpl, sbpl, escpos, starprnt, ipl. Default: "tsc".
	To string `json:"to" api:"to,required"`
	// Override DPI on the converted output.
	DPI *float64 `json:"dpi" api:"dpi"`
	// Override print speed, 1-18.
	Speed *float64 `json:"speed" api:"speed"`
	// Override print darkness, 0-15.
	Density *float64 `json:"density" api:"density"`
	// Override copies. Minimum 1.
	Copies *float64 `json:"copies" api:"copies"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelConvertParams holds the parameters of LabelConvert (POST /v1/label/convert). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelParams 

type LabelParams struct {
	// Use png so ChatGPT can display the image. svg is for download or infinite scale. Allowed values: svg, png. Default: "svg".
	Format *string `json:"format" api:"format"`
	// If true, persist the result and return share URLs instead of an image. Leave false to get the image. Default: false.
	Share *bool `json:"share" api:"share"`
	// Full label config as URL-encoded JSON. Must include width and elements. Text items use content and size (1-10), not text or fontSize.
	Query string `json:"query" api:"query,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelParams holds the parameters of Label (GET / POST /v1/label). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelParseParams 

type LabelParseParams struct {
	// Raw printer commands to parse. Also send language.
	Source string `json:"source" api:"source,required"`
	// Language of the source commands. Example: tsc or zpl. Allowed values: tsc, zpl, epl, cpcl, dpl, sbpl, ipl. Default: "tsc".
	Language string `json:"language" api:"language,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelParseParams holds the parameters of LabelParse (POST /v1/label/parse). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelRenderParams 

type LabelRenderParams struct {
	ID string `json:"id" api:"id,required"`
	// Override output format. Allowed values: svg, png. Default: "svg".
	Format *string `json:"format" api:"format"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelRenderParams holds the parameters of LabelRender (GET /v1/label/render/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelValidateParams 

type LabelValidateParams struct {
	// Raw printer commands to validate. Also send language.
	Source string `json:"source" api:"source,required"`
	// Language of the source commands. Example: tsc or zpl. Allowed values: tsc, zpl, epl, cpcl, dpl, sbpl, ipl. Default: "tsc".
	Language string `json:"language" api:"language,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelValidateParams holds the parameters of LabelValidate (POST /v1/label/validate). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type LabelViewParams 

type LabelViewParams struct {
	ID string `json:"id" api:"id,required"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

LabelViewParams holds the parameters of LabelView (GET /v1/label/view/{id}). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type QrcodeParams 

type QrcodeParams struct {
	// Data to encode in the QR code. Examples:
	Data string `json:"data" api:"data,required"`
	// Output size in pixels (width = height). Default: 200. Examples: ?size=200 (thumbnail), ?size=300 (standard), ?size=400 (large), ?size=600 (poster). For print, use the unit param with mm/cm instead.
	Size *float64 `json:"size" api:"size"`
	// Error correction level. Default: M. Higher levels allow more damage/obscuring before the code becomes unreadable. Allowed values: L, M, Q, H. Default: "M".
	EcLevel *string `json:"ec_level" api:"ec_level"`
	// Module (dot) shape. Default: square. Controls the visual style of each QR code module. Allowed values: square, rounded, dots, diamond, classy, classy-rounded, extra-rounded, vertical-line, horizontal-line, small-square, tiny-square. Default: "square".
	DotType *string `json:"dot_type" api:"dot_type"`
	// Module color as CSS hex. Default: #000. Examples: ?color=%236366f1 (indigo), ?color=%23dc2626 (red), ?color=%23059669 (green), ?color=%230891b2 (teal). Use %23 to URL-encode #. For gradient objects, use POST instead.
	Color *string `json:"color" api:"color"`
	// Overall QR code shape. Default: square. Use circle to clip the entire QR into a circle: great for profile/avatar-style codes. Example: ?shape=circle&dot_type=dots Allowed values: square, circle. Default: "square".
	Shape *string `json:"shape" api:"shape"`
	// Module size ratio between 0.1 and 1. Default: 1 (full). Values below 1 add spacing between modules for a lighter look. Example: ?dot_size=0.85
	DotSize *float64 `json:"dot_size" api:"dot_size"`
	// Background color. Default: #fff. Set to transparent for no background. Example: ?background=%230f172a for dark background. Use %23 to encode #.
	Background *string `json:"background" api:"background"`
	// Quiet zone width in modules around the QR code. Default: 4. Minimum recommended by the QR standard: 4. Example: ?margin=2 (compact) or ?margin=6 (extra padding).
	Margin *float64 `json:"margin" api:"margin"`
	// QR version from 1 to 40 (determines grid size and data capacity). Leave unset for auto-selection based on data length and ec_level. Example: ?version=5
	Version *float64 `json:"version" api:"version"`
	// Encoding mode. Default: auto (best mode selected for the data). Use numeric for digits-only, alphanumeric for uppercase + digits, byte for arbitrary text/UTF-8. Example: ?mode=numeric Allowed values: auto, numeric, alphanumeric, byte. Default: "auto".
	Mode *string `json:"mode" api:"mode"`
	// Mask pattern from 0 to 7. Default: auto (best mask selected to minimize visual patterns). Only set manually if you need a deterministic output. Example: ?mask=3
	Mask *float64 `json:"mask" api:"mask"`
	// Measurement unit for the size param. Default: px. Use mm, in or cm with the size param for print-ready output. Example: ?size=50&unit=mm Allowed values: px, mm, in, cm. Default: "px".
	Unit *string `json:"unit" api:"unit"`
	// Prepend an XML declaration (<?xml version="1.0" encoding="UTF-8"?>) to the SVG output. Useful when the SVG will be used as a standalone XML file. Default: false. Example: ?xml_declaration=true
	XMLDeclaration *bool `json:"xml_declaration" api:"xml_declaration"`
	// Accessible label added as aria-label on the SVG element. Example: ?aria_label=QR+code+linking+to+chartquery.com
	AriaLabel *string `json:"aria_label" api:"aria_label"`
	// SVG <title> element shown as a browser tooltip and used by screen readers. Example: ?title=ChartQuery+Website
	Title *string `json:"title" api:"title"`
	// SVG <desc> element for extended accessibility description. Example: ?desc=Scan+to+visit+https://chartquery.com
	Desc *string `json:"desc" api:"desc"`
	// Output format. Default: svg. Use png to get a raster image. SVG is lossless and scalable; PNG is pixel-based and suitable for email, PDF or messaging. Example: ?format=png Allowed values: svg, png. Default: "svg".
	Format *string `json:"format" api:"format"`
	// Set share=true to persist the config and receive JSON instead of an image: { id, render_url, view_url, embed_url, expires_in }. Free plan: 3-day expiry with watermark. Paid plan: 6-month expiry, no branding. Default: false.
	Share *bool `json:"share" api:"share"`
	// Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
	Fields *string `json:"fields" api:"fields"`
	// Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob). Default: false.
	IsAsync *bool `json:"is_async" api:"is_async"`
	// Return HTTP 200 even when an error occurs; the error is then in the response body. Default: false.
	SoftFail *bool `json:"soft_fail" api:"soft_fail"`
}

QrcodeParams holds the parameters of Qrcode (GET / POST /v1/qrcode). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type RequestOption 

type RequestOption func(*requestOptions)

RequestOption customizes one request.

func WithHeader 

func WithHeader(name, value string) RequestOption

WithHeader adds a header to one request.

func WithMaxRetries 

func WithMaxRetries(n int) RequestOption

WithMaxRetries overrides the number of retries for one request (0 disables them).

func WithMethod 

func WithMethod(method string) RequestOption

WithMethod selects GET or POST. Operations default to GET when they support it.

type Response 

type Response struct {
	StatusCode  int
	Header      http.Header
	ContentType string
	// Body holds the raw bytes: JSON text, or a file such as an image or PDF.
	Body []byte
	// IsJSON reports whether the body is JSON (Content-Type application/json or +json).
	IsJSON bool
}

Response is a buffered, successful API response.

func (*Response) Decode 

func (r *Response) Decode(v any) error

Decode unmarshals a JSON body into v.

func (*Response) Map 

func (r *Response) Map() (map[string]any, error)

Map decodes a JSON object body.

type ResponseDecodingError 

type ResponseDecodingError struct {
	Message  string
	Response *Response
	Err      error
}

ResponseDecodingError reports a success response that could not be decoded.

func (*ResponseDecodingError) Error 

func (e *ResponseDecodingError) Error() string

func (*ResponseDecodingError) Unwrap 

func (e *ResponseDecodingError) Unwrap() error

type SerializationError 

type SerializationError struct {
	Param   string
	Message string
	Err     error
}

SerializationError reports a parameter that is missing or cannot be sent.

func (*SerializationError) Error 

func (e *SerializationError) Error() string

func (*SerializationError) Unwrap 

func (e *SerializationError) Unwrap() error

type StatsParams 

type StatsParams struct {
	// API family to check, for example chart. Provide at least engine or path.
	Engine *string `json:"engine" api:"engine"`
	// Specific endpoint to check, for example /v1/chart. If you also pass engine, use an endpoint from that API.
	Path *string `json:"path" api:"path"`
}

StatsParams holds the parameters of Stats (GET /v1/stats). Required fields are plain values; optional fields are pointers (use chartquery.String, chartquery.Float, chartquery.Bool) or nil slices and maps.

type TransportError 

type TransportError struct {
	Message string
	Err     error
}

TransportError reports a failure before a complete HTTP response was received, including client-side timeouts and context cancellation (see Unwrap).

func (*TransportError) Error 

func (e *TransportError) Error() string

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

type WaitForJobOptions 

type WaitForJobOptions struct {
	Interval   time.Duration
	Timeout    time.Duration
	OnProgress func(job map[string]any)
}

WaitForJobOptions configures WaitForJob. The zero value polls after 3 s, then 1.5x longer each time up to 60 s, for up to 12 hours.

Source Files

View all Source files

Directories

Path Synopsis
examples
binary command
json command
request command
wait-for-job command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.