Skip to main content

API Vision

Our mission is to provide the most reliable, easy-to-use, and comprehensive weather intelligence. Whether you are building for Australia, New Zealand, or the globe, our data is the authority you trust. As we modernize our platform, we are guided by a set of design principles aimed at creating an exceptional developer experience.

Information in this document represents our Target State. While some of our Classic APIs may differ, all new Core APIs are built to these standards.

1. Predictable & Intuitive​

We believe that if you learn one of our APIs, you should intuitively understand the rest.

  • Consistent URLs: We use a standard structure (/product/version/resource) so you can guess where to find what you need.
  • Resource-Oriented: Our APIs are built around things (nouns), not actions. You fetch a /forecast, you don't call /getForecast.
  • Standard Auth: A single API key unlocks the entire platform.

2. Data Designed for Developers​

Weather data is complex, but using it shouldn't be. We design our JSON responses to be ready for your code, not just for scientific accuracy.

  • No "Object Tax": We flatten our data structures. You shouldn't have to dig through deep nesting (e.g., wind.speed.value) to get a simple number. We prefer wind_speed_10m.
  • Explicit Naming: We use "Glass Box" naming. Instead of a vague temp, we use air_temperature_2m so you know exactly what physics are being measured.
  • ISO Standards: All times are UTC and ISO 8601 formatted (YYYY-MM-DDTHH:MM:SSZ), reducing parsing errors across different languages.

3. Stability & Evolution​

We value your stability while we innovate.

  • Semantic Versioning: We use clear versioning (v1, v2) to protect your integrations from breaking changes.
  • Non-Breaking Evolution: We add new features and fields without breaking existing contracts.
  • Transparent Deprecation: When we do need to retire an old version, we commit to providing ample notice, clear migration guides, and support.

4. Helpful Troubleshooting​

When things go wrong, our APIs should help you fix it.

  • Problem Details: We don't just say "Error". We provide structured JSON error responses (based on RFC 9457) that tell you what went wrong and how to fix it.
  • Standard Codes: We use standard HTTP status codes (200, 400, 401, 403, 404, 429, 500) correctly, so your libraries handle them automatically.

This vision drives our roadmap. As we migrate our Classic APIs to the Core platform, you will see these principles applied more effectively across our entire catalogue.