Best Practices
Follow these recommendations to build reliable, performant integrations with the AccuWeather Enterprise API.
Performance
Use GZIP compression
All API responses support GZIP compression, which typically reduces payload size by 80% or more. Most modern HTTP clients enable this by default — ensure your client is not explicitly disabling it.
Add the Accept-Encoding header to your requests:
Use connection pooling
If you are making frequent API calls, reuse HTTP connections rather than opening a new connection per request. Most HTTP client libraries support keep-alive and connection pooling out of the box.
Caching
Respect cache headers
Every API response includes cache headers that indicate when the data will next be updated. Use these headers to avoid unnecessary requests.
Code
Cache-Control: max-age— the number of seconds the response can be cachedExpires— the absolute time after which the response should be refreshed
Do not request new data until the cache has expired. This reduces unnecessary load and ensures your application always uses the freshest available data.
Randomize refresh times
If you are refreshing data across many devices or services, add randomization to prevent all clients from requesting updates at the same clock time (e.g., exactly on the hour). Stagger requests by adding a random offset of a few seconds or minutes to each client's refresh interval.
Cache MinuteCast™ errors
MinuteCast™ is not available in all regions. For unsupported locations, the API returns an HTTP 400 response. Cache these responses for 72 hours to avoid repeated requests for locations where MinuteCast™ data is not available.
Error handling
Distinguish client and server errors
Handle 4xx and 5xx errors differently:
- 4xx errors (Bad Request, Forbidden, Not Found, Conflict) indicate a problem with the request itself. Do not retry these without fixing the underlying issue (e.g., invalid API key, bad parameters, exceeded quota).
- 5xx errors (Internal Error, Service Unavailable) indicate a temporary server-side issue. Retry these with exponential backoff.
Retry with exponential backoff
For transient failures (5xx responses, network timeouts), retry with increasing delays:
Time zones and daylight saving
If you use the GMTOffset from the Locations API to calculate local times, you must observe the NextOffsetChange property. The offset will change at the date and time specified when a location transitions into or out of Daylight Saving Time.
Respecting cache headers (as described above) ensures you always have the most current offset for a location.
Monitoring
Stay informed on service availability for AccuWeather products and services at status.accuweather.com. Subscribe to updates to receive notifications about planned maintenance and incidents.