Zingu API SDK

Official Python SDK for interacting with the Zingu API catalog. Query any API by slug, with automatic pagination and endpoint methods. JavaScript SDK coming soon.

Quick Start

import zingu_apis

# Get an API handle by slug
api = zingu_apis.api("dayinhistory")

# Call endpoint as method with parameters
result = api.events_month_day(month="july", day=4, max_items=5)

# Or use fetch() with path template and params dict
result = api.fetch("events/{month}/{day}", params={"month": "july", "day": 4}, max_items=5)

# Or use fetch() with positional params as list
result = api.fetch("events/{month}/{day}", params=["july", 4], max_items=5)

# Or use fetch() with literal path (slashes optional)
result = api.fetch("events/july/4", max_items=5)

# Iterate over results
for event in result:
    print(f"{event['year']}: {event['title']}")

# Access analytics
print(f"Fetched {len(result)} events in {result['analytics']['elapsed_ms']}ms")

# Discover available methods
print(api.help())          # Shows all endpoint methods
print(api.tools())         # Returns dict of {method_name: {path, description}}

# Get method name from path (leading/trailing slashes optional)
method_name = api.get_method_name("events/{month}/{day}")  # -> "events_month_day"

# Get callable method from path
method = api.get_method("events/{month}/{day}")
result = method(month="july", day=4, max_items=5)

# Get parameters for an endpoint
params = api.get_method_parameters("events/{month}/{day}")
# -> [{"name": "month", "type": "string"}, {"name": "day", "type": "string"}]

Discovering Endpoints

Each API exposes its endpoints as methods. To see what's available:

# Print all available methods with their signatures
print(api.help())

# Returns a dict of {method_name: {path, method, description}}
endpoints = api.tools()
for name, info in endpoints.items():
    print(f"{name}: {info['path']}")

Endpoint Metadata

Each endpoint method has a .info() function that returns metadata:

method = api.get_method("events/month/day")
info = method.info()

print(info)
# {
#     'method': 'GET',
#     'path': '/events/{month}/{day}',
#     'description': 'Get historical events for a specific date',
#     'response_content_type': 'application/json',
#     'pagination': {'style': 'page_number', 'results_key': 'results'},
#     'parameters': None  # or dict of parameter metadata
# }

Method names are derived from endpoint paths (leading/trailing slashes optional):

• /events/{month}/{day} → api.events_month_day(month=..., day=...)
• /today/events → api.today_events()

Features

• Type Safety — Full Python type hints included
• Authentication — Built-in API key and OAuth2 support
• Auto-Retry — Automatic retries with exponential backoff
• Rate Limiting — Respects API rate limits with queuing
• Caching — Optional response caching for repeated requests
• Error Handling — Structured exceptions with detailed error messages

Repository & Documentation

The GitHub repo for the package is https://github.com/zingu-ai/zingu-apis

View on GitHub →

The GitHub repository includes:

• Usage examples for common operations

Installation

Python

pip install git+https://github.com/zingu-ai/zingu-apis.git

JavaScript

Coming soon.

Configuration

The SDK works out of the box. No configuration needed.

For APIs that require authentication, pass your API key:

api = zingu_apis.api("stripe", key="your-api-key")

# Call endpoints as methods with parameters
result = api.charges_create(amount=2000, currency="usd")

Support

For issues, feature requests, or contributions:

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions and community support