# 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: ```bash 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: ```bash 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: ```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!