Skip to main content

​
Overview

For large payloads (>1MB), you can compress your request body with gzip to send up to 10x larger datasets without any API changes.

​
When to Use Compression

Use compression when:
  • Request payload > 1MB
  • Large timeseries datasets (thousands of data points)
  • Large tables (hundreds of rows)
  • You receive “Request body exceeds maximum allowed size” errors
Skip compression when:
  • Payload < 100KB (overhead isn’t worth it)
  • Simple charts with few data points

​
Size Limits

ScenarioMaximum Size
Without compression3.5MB
With gzip (compressed)2.5MB compressed
With gzip (effective uncompressed)~25MB (typical 10x compression for JSON)
Hard limits2.5MB compressed, 50MB uncompressed

​
How It Works

  1. Compress your request body with gzip
  2. Add the Content-Encoding: gzip header
  3. Send the request normally
The API automatically detects and decompresses gzipped requests.
This is completely optional and backward compatible. Existing uncompressed requests continue to work without any changes.

​
Examples

import requests
import gzip
import json

# Your data (example: large timeseries)
data = {
    "title": "High-Frequency Stock Data",
    "components": [
        {
            "component_type": "header",
            "config": {"title": "AAPL - Minute by Minute"}
        },
        {
            "component_type": "generic_timeseries",
            "config": {
                "datasets": [
                    {
                        "label": "Price",
                        "data": [
                            {"x": f"2024-01-01T09:{m:02d}:00", "y": 150.0 + (i * 0.1)}
                            for i, m in enumerate(range(10000))
                        ],
                        "type": "line",
                        "units": "$"
                    }
                ]
            }
        }
    ]
}

# Compress the JSON
json_bytes = json.dumps(data).encode('utf-8')
compressed = gzip.compress(json_bytes)

print(f"Original: {len(json_bytes) / 1024:.1f}KB")
print(f"Compressed: {len(compressed) / 1024:.1f}KB")
print(f"Saved: {(1 - len(compressed) / len(json_bytes)) * 100:.1f}%")

# Send compressed request
response = requests.post(
    "https://api.trytako.com/api/v1/thin_viz/create/",
    headers={
        "X-API-Key": "your-api-key",
        "Content-Type": "application/json",
        "Content-Encoding": "gzip"  # Important!
    },
    data=compressed  # Send compressed bytes, not JSON
)

card = response.json()
print(f"Created: {card['webpage_url']}")

​
Example Output

Original: 3,456.2KB
Compressed: 342.1KB
Saved: 90.1%
Created: https://tako.com/card/xyz789/

​
Python Helper Function

Here’s a reusable helper function that automatically compresses when beneficial: 
import requests
import gzip
import json
from typing import Dict, Any

def create_thinviz_card(
    data: Dict[str, Any],
    api_key: str,
    compress: bool = True,
    base_url: str = "https://api.trytako.com"
) -> Dict[str, Any]:
    """
    Create a ThinViz card with optional compression.

    Args:
        data: Card configuration dict
        api_key: Your Tako API key
        compress: Whether to use gzip compression (default: True)
        base_url: API base URL

    Returns:
        Card response dict with webpage_url, embed_url, etc.
    """
    url = f"{base_url}/api/v1/thin_viz/create/"
    headers = {
        "X-API-Key": api_key,
        "Content-Type": "application/json"
    }

    if compress:
        # Compress the payload
        json_bytes = json.dumps(data).encode('utf-8')
        compressed = gzip.compress(json_bytes)
        headers["Content-Encoding"] = "gzip"
        payload = compressed

        print(f"Compressed {len(json_bytes) / 1024:.1f}KB → {len(compressed) / 1024:.1f}KB")
    else:
        payload = json.dumps(data)

    response = requests.post(url, headers=headers, data=payload)
    response.raise_for_status()
    return response.json()

# Usage
card = create_thinviz_card(
    data={
        "title": "My Chart",
        "components": [...]
    },
    api_key="your-api-key",
    compress=True
)

print(f"Card created: {card['webpage_url']}")

​
Important Notes

Keep Content-Type: application/json - Don’t change the content type header. Only add Content-Encoding: gzip.
Only compress the body - Headers should remain uncompressed. Only the request body should be gzipped.
Safety limits - Requests with compression ratio >100:1 are rejected to prevent decompression bomb attacks.

​
Error Handling

If your payload is too large, you’ll receive this error: 
{
    "error": "Request body exceeds maximum allowed size",
    "message": "Your request payload is too large. For large datasets, compress your request body with gzip and include the 'Content-Encoding: gzip' header to send payloads up to 10x larger.",
    "suggestion": "See API documentation for compression examples in Python, JavaScript, and other languages."
}
Follow the examples above to add compression and retry.

​
Best Practices

  1. Use compression for large datasets - Anything over 1MB benefits significantly
  2. Cache compressed payloads - If sending the same data multiple times, compress once
  3. Monitor compression ratios - Typical JSON compresses 8-12x with gzip
  4. Test with small data first - Validate your structure before scaling up

​
Applicable Endpoints

Compression works with all Tako API endpoints that accept JSON request bodies:
  • /v1/thin_viz/create/ - ThinViz direct create
  • /v1/thin_viz/default_schema/{name}/create/ - Schema-based create
  • /v1/beta/visualize - Visualize API
  • /v1/beta/visualize/stream - Streaming visualize
  • And more…