Api is up and running

Hello v.3, Goodbye v.2: Technical Details

Greetings subscribers, friends, neighbors, and interested parties! We’re excited to announce that we’re releasing a new major version of our weather API in March! This will be our 3rd major version.

We’ve taken a lot of feedback from our API community over the last year, and our v.3 API is the result. The enhancement requests we got were such that they wouldn’t allow backward compatibility. The changes aim to follow best practices more closely, and make the API easier to use.

Enhancements include:

  • Better weather data
    • The v.3 API has incorporated historical and real-time data that our scientists have been hard at work to provide. The v.2 API has access to includes tens of thousands of monitoring stations around the world. In contrast, the v.3 API estimates weather conditions at over 20 million points in the United States alone.
    • The v.3 API will have even more accurate real-time precipitation than v.2, which was already industry-leading.
    • The v.3 API will have 6 hours of historical data available globally, while v.2 didn’t have any global history.
  • Better error messages
    • Our new errors are designed to help you troubleshoot any issues.
    • For example, we’re replacing “The input you provided is not correct.” with “You must specify a valid lat/lon or location_id” when you haven’t specified a location.
  • Faster responses
  • Weather layer improvements
    • In response to customer feedback, we’ve added new weather layers, which include cloud_cover, cloud_ceiling, cloud_base, visibility, and wind_gust.
    • Higher accuracy – we’ve made improvements to fine-tune the layers we give you.

If you use our v.2 API, please upgrade to use our new and improved v.3 API by May, when v.2 will be gone! As you transition, here are the key technical differences to keep in mind between the v.2 API and the v.3 API.

  • All data retrieval endpoints will use the GET method .
    • In v.2, some of our weather endpoints used a POST request from users, with users specifying requested fields within the body of the POST request.
    • In v.3, users will specify requested fields using query parameters.
    • The endpoints making this change are /realtime (now), /nowcast (6-hour forecast), and /historical.
  • Our error messages are getting better!
    • In v.2, our 400 message states “The input you provided is not correct.” In v.3, we’ll be more explicit and tell you how to change your request.
    • The error format will change slightly from being a simple string message, to:
      {
      “statusCode”: <status code, e.g. 400>,
      “errorCode”: <error code, e.g. BadRequest>,
      “message”: <error message>,
      “data”: <optional JSON object>
      }
  • Fields and unit overrides will be provided together in one query parameter, to simplify request construction.
    • https://{baseURL}/weather/realtime?lat={}&lon={}&fields=precipitation:in,temperature:F
  • Barometric pressure will be reported in hPa. In v.2, it was reported in kPa, which isn’t an SI unit.
  • v.3 will be faster than v.2.
    • Many of our v.2 endpoints are snappy, but some are not. With the release of our v.3 API, we’re aiming for responses that take no longer than 250ms. There may be a few outliers, but overall we’re realizing a dramatic improvement.
    • In v.2, it’s possible to make API calls that timeout, because too much data has been requested. In V3, we’ll limit request-able time ranges, so that you don’t have to guess how many days worth of data you can get at once.
  • We’re adding new weather layers, and sourcing weather field data from our own proprietary weather data.
    • We’ve developed a new iteration of our proprietary real-time weather analysis system to provide the best estimate of the weather at the point you care about.
    • This increase in the number of data points translates to better weather resolution for each location.
    • As soon as v.3 is released, this will apply to our /realtime and /historical endpoints.
    • New layers include cloud_cover, cloud_ceiling, cloud_base, visibility, and wind_gust.
    • Existing fields will get a big upgrade with our own data, which estimates weather conditions at over 20 million points in the United States alone, as opposed to the tens of thousands that are available from governmental stations (which is what most APIs report).
  • Default data responses will be smaller.
    • We will only return the precipitation and precipitation_type by default if no weather fields are specified in the request. This will keep payloads small for testing and mobile purposes, and will allow us to release new fields in a backward-compatible way.
  • The /nowcast endpoint will only return precipitation and precipitation_type when first released.
    • In order to give you access to the best weather information, v.3 nowcast will return 100% proprietary data. We still have work to do to make that happen for all of the weather fields for nowcast – expect to see fields added back in Q3 of 2019.
    • Update 2/25/19: We are pleased to report that nowcast WILL return all of the fields that it currently does in v.2. There will be no loss of functionality as was originally planned.
  • More endpoints will have start_time, end_time, and timestep available as request parameters, for endpoints that include time ranges.
    • We want to give you consistent access to specific time ranges. In v.2, our /hourly endpoint doesn’t allow this.
    • These new fields will be optional, with defaults set.
  • The base URL will change between v.2 and v.3, and URL paths will vary slightly between v.2 and v.3.
    • The base URL for v.3 is api.climacell.co/v3
    • Weather endpoints will have an additional path parameter, e.g. api.climacell.co/v3/weather/nowcast
  • There will be TWO historical API endpoints in v.3.
    • One endpoint will retrieve information from METAR and other physical stations.
      • Data will be available from 4 weeks in the past to now.
    • One endpoint will retrieve information from proprietary sources. This dataset will include a greater number of API fields and will cover the globe more completely.
      • Data will be available from 4 weeks in the past to now.

We’re planning to release our v.3 API in March, and to retire our v.2 API in May. Thank you for being part of our API community!