Migrating from APIv3

In December 2020, we released version 4 of Tomorrow.io REST Weather API (previously ClimaCell) and announced that version 3 will be sunset on June 1, 2021. On this date, all requests made against v3 will fail. This guide explains how to update your application for compatibility with v3. We recommend migrating as soon as possible to ensure that your application is unaffected.

This guide covers the following endpoints:

  • GET /weather/realtime
  • GET /weather/nowcast
  • GET /weather/forecast/hourly
  • GET /weather/forecast/daily
  • GET /weather/historical/climacell
  • GET /weather/layers/field/now/zoom/x/y.png

Note

In APIv4, all of the numerical data can be requested with a single call to the /timelines endpoint.

Migration Checklist

  • Sign up to APIv4
  • Familiarize yourself with the new v4 syntax
  • Update your app's code, replacing API v3 calls with API v4 calls
  • Update the error handling in your app to utilize v4 errors

In case you were on a paid plan, reach out to [email protected] to ensure that your plan limits are allocated accordingly on the next version.

Syntax Comparison

Attribute

v3

v4

Base URL

api.climacell.co/v3`

api.tomorrow.io/v4

Naming Conventions

snake_case

camelCase

Location Formats

Latlong pairs as separate parameters

Latlong pairs as query array parameter LAT,LONG, body parameter [LAT,LONG], or GeoJSON geometry (longlat coordinates)

"Now" Timestep

now string supported as timestep

startTime as null defaults to now

Field Descriptors

Large payloads due to repetitive units for each time interval

Numerical values only, mapped to units/enums on the application side (except for fields ending with Time, which is in ISO 8601 format)

Nested Responses

Large payloads due to unnecessary nesting (like observation_time and field names holding value)

Flatter payloads, mapping each interval's `values, whereas field names are keys.

To learn more about the new design of the HTTP endpoints and other accepted URL parameters, read the beginning of the full REST API reference docs.

Realtime

Get the first interval of the "1m" timestep data - in case endTime is not provided it defaults to the max of 360 minutes out

Note

In the upcoming weeks we will introduce another timestep - current - as syntactic sugar returning only this interval per request.

curl --request GET \
  --url 'https://api.climacell.co/v3/weather/realtime?lat=LAT&lon=LONG&unit_system=si&fields=FIELD_NAME'
curl --request GET \
  --url 'https://api.tomorrow.io/v4/timelines?location=LAT%2CLONG&fields=FIELD_NAME&timesteps=current'

Nowcast

Request "1m" timestep - in case endTime is not provided it defaults to the max of 360 minutes out

curl --request GET \
  --url 'https://api.climacell.co/v3/weather/nowcast?lat=LAT&lon=LONG&unit_system=si&timestep=5&start_time=now&fields=FIELD_NAME'
curl --request GET \
  --url 'https://api.tomorrow.io/v4/timelines?location=LAT%2CLONG&fields=FIELD_NAME&timesteps=5m'

Hourly

Request "1h" timestep - in case endTime is not provided it defaults to the max of 108 hours out

curl --request GET \
  --url 'https://api.climacell.co/v3/weather/forecast/hourly?lat=LAT&lon=LONG&unit_system=si&start_time=now&fields=FIELD_NAME'
curl --request GET \
  --url 'https://api.tomorrow.io/v4/timelines?location=LAT%2CLONG&fields=FIELD_NAME&timesteps=1h'

Daily

Request "1d" timestep and field with Min/Max/MinTime/MaxTime suffix - in case endTime is not provided it defaults to the max of 15 days out

curl --request GET \
  --url 'https://api.climacell.co/v3/weather/forecast/daily?lat=LAT&lon=LONG&unit_system=si&start_time=now&fields=FIELD_NAME'
curl --request GET \
  --url 'https://api.tomorrow.io/v4/timelines?location=LAT%2CLONG&fields=FIELD_NAME&timesteps=1d'

Historical

Request any timestep and field with Min/Max/MinTime/MaxTime suffix - in case endTime is not provided it defaults to the max of that timestep (slips into forecast time frame)

curl --request GET \
  --url 'https://api.climacell.co/v3/weather/historical/climacell?lat=LAT&lon=LONG&timestep=5&unit_system=si&fields=FIELD_NAME'
curl --request GET \
  --url 'https://api.tomorrow.io/v4/timelines?location=LAT%2CLONG&fields=FIELD_NAME&startTime=START_TIME&endTime=END_TIME&timesteps=5m'

Tiles

Request any of the supported fields (marked with M) - in case time and format are not provided it defaults "now" and ".png"

curl --request GET \
  --url https://api.climacell.co/v3/weather/layers/FIELD_NAME/now/ZOOM/X/Y.png
curl --request GET \
  --url https://api.tomorrow.io/v4/map/tile/ZOOM/X/Y/FIELD_NAME