Times Adder Getting Started: Account, Keys & First Request

Getting started overview

Getting started with Times Adder involves a sequence of steps designed to enable rapid integration for time series data analysis and aggregation. This guide outlines the process from account creation to executing a foundational API request. The Times Adder platform is structured to provide tools for real-time data aggregation, financial data analysis, IoT sensor data processing, and predictive maintenance. Developers can use the available Software Development Kits (SDKs) in Python, JavaScript, and Go to streamline interactions with the API.

The core process includes:

1. Account Creation: Signing up for a Times Adder account.
2. API Key Retrieval: Generating and securing the necessary API credentials.
3. Environment Setup: Configuring your development environment for API calls.
4. First Request: Making an authenticated call to a Times Adder endpoint.

Times Adder offers a Developer Plan that provides up to 5,000 free requests per month, which enables initial development and testing without immediate cost. For more extensive usage, paid plans begin at $29/month for 50,000 requests, as detailed on the Times Adder pricing page.

The following table provides a quick reference for the initial setup steps:

Create an account and get keys

Access to the Times Adder API requires an account and associated API keys for authentication. These keys verify your identity and authorize your requests against the API endpoints.

Account Creation

To create a Times Adder account:

1. Navigate to the Times Adder homepage.
2. Click on the "Sign Up" or "Get Started Free" button.
3. Provide the required registration details, typically including an email address and a password.
4. Follow any on-screen prompts for email verification or initial setup.

Upon successful registration, you will gain access to the Times Adder developer dashboard.

Retrieving API Keys

API keys are essential for authenticating your requests. It is a common practice for APIs to use secret keys, often in conjunction with environment variables, to protect credentials. For example, AWS recommends managing access keys securely by avoiding hardcoding them in code and utilizing environment variables or configuration files for storage (AWS access keys best practices). Similarly, Times Adder API keys should be handled with care.

To retrieve your Times Adder API key:

1. Log in to your Times Adder developer dashboard.
2. Locate the "API Keys" or "Credentials" section, usually found in the navigation menu or settings.
3. Generate a new API key if one is not already present, or copy an existing active key.
4. Securely store this key. Do not embed it directly into your source code. Instead, use environment variables or a secure configuration management system.

The API key functions as a bearer token or a header value, authenticating your requests to the Times Adder API (Times Adder API authentication documentation).

Your first request

After acquiring your API key, the next step is to make an authenticated request to a Times Adder endpoint. This example uses the Python SDK for its first-class support and comprehensive documentation (Times Adder documentation).

Setting up the Python Environment

First, ensure you have Python installed. Then, install the Times Adder Python SDK using pip:

pip install timesadder

It is recommended to use a virtual environment to manage project dependencies. For example, Python's venv module allows creation of isolated Python environments (Python venv documentation).

Making an Aggregation Request

This example demonstrates how to use the Time Series Aggregation API to sum values over a specified time range, a common operation for time series data. Ensure your API key is stored as an environment variable (e.g., TIMESADDER_API_KEY).

import os
from timesadder import TimesAdderClient
from datetime import datetime, timedelta

# Retrieve API key from environment variable
api_key = os.environ.get("TIMESADDER_API_KEY")
if not api_key:
    raise ValueError("TIMESADDER_API_KEY environment variable not set.")

# Initialize the client
client = TimesAdderClient(api_key=api_key)

# Define parameters for the aggregation request
# Example: Aggregate data for the last 24 hours
end_time = datetime.utcnow()
start_time = end_time - timedelta(days=1)

data_source_id = "your_data_source_identifier" # Replace with your actual data source ID
# The 'field' parameter specifies which data point to aggregate
field_to_aggregate = "temperature_celsius" 

try:
    # Make the aggregation call
    response = client.time_series.aggregate_sum(
        data_source_id=data_source_id,
        field=field_to_aggregate,
        start=start_time.isoformat() + "Z", # ISO 8601 format with Z for UTC
        end=end_time.isoformat() + "Z"
    )

    # Process the response
    print(f"Aggregation successful. Status: {response.status}")
    print(f"Total sum for {field_to_aggregate}: {response.data.sum}")
    print(f"Aggregated data points: {response.data.count}")

except Exception as e:
    print(f"An error occurred during aggregation: {e}")
    # Detailed error handling based on API response structure
    if hasattr(e, 'response') and e.response is not None:
        print(f"API Error Details: {e.response.text}")

Explanation of the code:

• os.environ.get("TIMESADDER_API_KEY"): Safely retrieves your API key, preventing it from being hardcoded.
• TimesAdderClient(api_key=api_key): Initializes the SDK client with your credentials.
• datetime.utcnow() and timedelta: Used to define a time window for the aggregation, typically in UTC for time series data consistency.
• client.time_series.aggregate_sum(...): Calls the specific endpoint for summing data.
• data_source_id: A unique identifier for the specific stream of time series data you wish to query. This must be set up within your Times Adder account and populated with data.
• field: The specific metric or attribute within your data source that you intend to aggregate.
• start and end: Define the time window for the aggregation, formatted as ISO 8601 strings with 'Z' for UTC.
• Error Handling: Includes a try-except block to catch potential API errors or network issues, printing relevant details from the API response if available.

To run this code, replace "your_data_source_identifier" and "temperature_celsius" with parameters relevant to your Times Adder setup and data.

Common next steps

After successfully making your first API call, you can explore more advanced features and integrations:

• Explore Other Endpoints: Consult the Times Adder API Reference for details on the Anomaly Detection API, Forecasting API, and other aggregation types (e.g., average, min, max, count).
• Data Ingestion: Learn how to send your own time series data to Times Adder. This typically involves using an ingestion endpoint, often with batching or streaming methods.
• Webhooks and Notifications: Set up webhooks to receive real-time notifications for events like anomaly detection alerts or completion of long-running tasks. Webhooks are a common pattern for event-driven architectures, as described in Mozilla's Webhook Glossary entry.
• Monitoring and Logging: Implement monitoring for your API usage and integrate with logging solutions to track requests and responses, aiding in debugging and performance analysis.
• Scalability and Optimization: For high-volume applications, consider strategies like request batching, efficient data modeling, and understanding rate limits to optimize your usage of the Times Adder API.
• Explore SDKs: If Python is not your primary language, investigate the JavaScript or Go SDKs for Times Adder to integrate with other parts of your tech stack.

Troubleshooting the first call

Encountering issues during the initial API call is common. Here are some troubleshooting steps:

• Check API Key:
  • Validity: Ensure your API key is correct and has not expired or been revoked. Regenerate it from the Times Adder dashboard if necessary.
  • Placement: Verify that the API key is correctly passed in the request headers or client initialization as specified in the Times Adder API authentication documentation.
  • Environment Variable: If using environment variables, double-check that the variable is set in the shell where you are running your script. For example, on Linux/macOS: export TIMESADDER_API_KEY="your_key_here".
• Review Error Messages:
  • Times Adder's API is designed to return descriptive error messages (Times Adder developer experience notes). Parse the API response for specific error codes (e.g., 401 Unauthorized, 400 Bad Request, 404 Not Found) and messages.
  • Common HTTP status codes are standardized and provide general guidance on the nature of an error, such as 401 Unauthorized indicating issues with authentication credentials (MDN Web Docs 401 Unauthorized).
• Verify Data Source ID and Field:
  • Ensure that the data_source_id you are querying actually exists in your Times Adder account and contains data.
  • Confirm that the field you are trying to aggregate is present within the specified data source and is correctly spelled.
• Time Range Format:
  • Double-check that start and end timestamps are in the correct ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ), including the 'Z' for UTC if applicable.
• Network Connectivity:
  • Confirm your development environment has an active internet connection and no firewall rules are blocking outbound requests to the Times Adder API endpoints.
• SDK Version:
  • Ensure you are using the latest version of the Times Adder SDK. Outdated SDKs might have compatibility issues or missing features. Update with pip install --upgrade timesadder.
• Consult Documentation:
  • Refer to the official Times Adder documentation for detailed guides, examples, and the specific requirements for each API endpoint.