Python API for Google Visualization

Warnings

• gotcha The gviz-api library is stable but has not seen significant updates since its last release in October 2021. It originated as an 'automatically exported' project, indicating limited ongoing development on GitHub.
  Fix: While functional for its intended purpose, users should be aware that active feature development or frequent bug fixes may not be available. Consider community forks or alternative solutions for new requirements.
• gotcha The library enforces strict type checking based on the schema definition. It does not perform automatic type coercion. Providing data that does not precisely match the declared type (e.g., a string '123' for a numeric column) will raise a `TypeError`.
  Fix: Ensure all data elements conform exactly to their declared Python types before appending to the `DataTable`. For example, use `int(value)` or `float(value)` explicitly for numeric conversions.
• gotcha Once a `DataTable` object is created with a schema, the column definitions (schema) cannot be modified. Additionally, individual rows cannot be removed, though new rows can be appended, or the entire data can be overwritten.
  Fix: Plan your table schema carefully before initialization. If dynamic column modification or individual row deletion is needed, preprocess your data into the final desired structure before creating the `DataTable`.
• gotcha This Python library is purely for generating data in a format compatible with the Google Visualization API. It does not provide any functionality for rendering charts or visualizations itself. Rendering must be handled by client-side JavaScript in a web browser.
  Fix: You must include the Google Charts JavaScript library in your web page and write JavaScript code to fetch the data generated by `gviz-api` and draw the desired visualization.

Install

• pip install gviz-api Install latest version

Imports

• DataTable

  from gviz_api import DataTable

  The primary class for creating data tables.
• gviz_api

  import gviz_api

  Import the module directly to access its functions and classes.

Quickstart

This quickstart demonstrates how to define a table schema, populate it with data, and output the `DataTable` in different formats (JSON, JSON Response, JavaScript string) suitable for consumption by Google Charts.

import gviz_api
import datetime

# Define the schema of the table.
# The structure is: [(id, type, optional_label), ...]
description = [
    ("name", "string", "Meal"),
    ("diet", "string", "Diet Type"),
    ("calories", "number", "Calories"),
    ("healthy", "boolean", "Healthy?"),
    ("serving_date", "date", "Serving Date")
]

# Load the data. Data rows must match the schema order.
data = [
    ("Breakfast", "vegan", 250, True, datetime.date(2024, 4, 13)),
    ("Lunch", "vegetarian", 400, True, datetime.date(2024, 4, 13)),
    ("Dinner", "carnivore", 700, False, datetime.date(2024, 4, 12)),
    ("Snack", "omnivore", 150, True, datetime.date(2024, 4, 13)),
]

# Create a DataTable object.
data_table = gviz_api.DataTable(description)
data_table.AppendData(data)

# Output as JSON string (for embedding in a webpage)
json_string = data_table.ToJSon(columns_order=("name", "diet", "calories", "healthy", "serving_date"), order_by="calories")
print("JSON String:\n", json_string)

# Output as JSON response string (for a data source URL)
# req_id is often 0 for simple requests.
json_response = data_table.ToJSonResponse(columns_order=("name", "calories"), order_by="calories", req_id=0)
print("\nJSON Response (for data source):\n", json_response)

# Output as JavaScript string (for direct script injection, often for debugging)
javascript_string = data_table.ToJS(table_id="myDataTable", columns_order=("name", "calories"), order_by="calories")
print("\nJavaScript String (for embedding):\n", javascript_string)