Responsible Use of Wia API

At Wia, we aim to provide seamless access to energy, gas, and water data while ensuring system stability and fairness for all users. This guide outlines the best practices and policies for responsible use of the Wia API, including rate limits and guidelines for efficient integration.

API Rate Limits

To maintain system performance and availability, the Wia API imposes the following rate limit:

• 100 requests per minute per API key

If you exceed this limit, further requests will be temporarily blocked until the rate limit resets.

Best Practices to Stay Within Limits

1. Batch Your Requests: Where possible, combine multiple queries into a single request (e.g., retrieving data for multiple devices or time ranges).
2. Implement Caching: Cache responses locally to minimize duplicate API calls for frequently accessed data.
3. Retry Logic: Implement exponential backoff for retries if you encounter rate limit errors (HTTP status code 429).
4. Monitor Your Usage: Regularly monitor your API usage to ensure you stay within the allowed limits.

Efficient Data Retrieval

Use Time Intervals

Specify appropriate time intervals to avoid retrieving excessive data at once. Example:

curl -X GET "https://api.wia.io/v1/energy/electricity?since=2024-01-01T00:00:00Z&until=2024-01-02T00:00:00Z"

Filter by Relevant Parameters

Always use filters to narrow down results, such as specifying space.id or device.id to focus on relevant data:

curl -X GET "https://api.wia.io/v1/energy/electricity?space.id=spc_abc123"

Avoiding Misuse

• Do Not Share API Keys: Keep your API keys secure and do not share them with unauthorized parties.
• Follow Rate Limits: Adhere to the rate limits to avoid service disruptions.
• Use Data Responsibly: Ensure that data retrieved from Wia is used in accordance with applicable laws and regulations.

Error Handling

Common Errors

• 429 Too Many Requests: Indicates that the rate limit has been exceeded. Wait for the reset period before making additional requests.
• 400 Bad Request: Check your request parameters for errors.
• 401 Unauthorized: Ensure your API key is correct and active.

Example Retry Logic

In the event of a 429 error, implement retry logic with exponential backoff. Example in pseudocode:

attempts = 0
while attempts < max_attempts:
    response = make_api_request()
    if response.status_code == 429:
        wait_time = 2 ** attempts  # Exponential backoff
        sleep(wait_time)
        attempts += 1
    else:
        break

Monitoring Usage

Leverage Wia’s dashboard or logs to track your API usage and identify patterns that may require optimization. Stay proactive to avoid hitting rate limits.

By following these guidelines, you can ensure a smooth and efficient experience with the Wia API while contributing to system stability for all users. Thank you for using Wia responsibly!