Tomorrow.io LLM-Friendly Weather API Documentation

Weather Codes Reference

Free

⚠️ Important: The weatherCode field only includes basic weather conditions (i.e., "clear") and does not include mixed conditions ("partly cloudy and fog").

🚨 API Status Update: As of June 2024, only the basic weatherCode field is currently available in API responses. The weatherCodeFullDay, weatherCodeDay, and weatherCodeNight fields documented below are not yet returned by the API, despite being mentioned in official documentation.

For a complete set of daily conditions, please use the new weatherCodeFullDay (calculated from sunrise to sunrise), weatherCodeDay (calculated from sunrise to sunset), and weatherCodeNight (calculated from sunset to sunrise).

Is it foggy? Rainy? A clear day? If you need a description of what the weather is like, simply request the weather code.

Weather Code Types Overview

Tomorrow.io provides four distinct weather code fields, each designed for specific use cases and time periods:

Basic Weather Code

weatherCode

Basic weather conditions only. Does not include mixed conditions like "partly cloudy and fog".

Limited condition set

Full Day Weather Code

weatherCodeFullDay

Complete daily conditions from sunrise to sunrise. Includes mixed conditions.

Comprehensive daily coverage

Day Weather Code

weatherCodeDay

Daytime conditions from sunrise to sunset. Uses "Clear" terminology.

Codes ending in 0 (e.g., 10000)

Night Weather Code

weatherCodeNight

Nighttime conditions from sunset to sunrise. Uses "Clear" instead of "Sunny".

Codes ending in 1 (e.g., 10001)

Weather Icons Library

As Tomorrow.io REST Weather API consumers, you have full access to the library of weather icons to accompany weather codes for visual representation.

Official Weather Icons Access

Tomorrow.io provides full access to the weather icons library for API consumers:

Icons Repository: github.com/tomorrow-io-api/tomorrow-weather-codes

Official Documentation: docs.tomorrow.io/reference/data-layers-weather-codes

Attribution Required: Be sure to place a "Powered by Tomorrow.io" attribution in your application if you use the weather icons.

Weather Icon Integration

Local Weather Icons

Weather icons are hosted locally in this project for reliable access:

/weather-icons/[icon-hash]-weather_icon_small_ic_[condition]3x.png

• High-resolution 3x PNG format
• Separate day and night variants
• Optimized for web and mobile apps
• Hosted locally for reliable access

Icon Library Resources

• GitHub Repository: Complete icon collection with SVG, PNG formats
• V2 Icons: Updated designs with mixed weather conditions
• V1 Icons: Original 23 basic weather types
• Design Assets: Figma resources for UI design
• License: CC BY 4.0 with attribution requirement

Implementation Example

Dynamically load weather icons based on weather code and time of day:

// Example: Clear weather (code 1000) const isDaytime = new Date().getHours() > 6 && new Date().getHours() < 18; const iconUrl = isDaytime ? "/weather-icons/48b265b-weather_icon_small_ic_clear3x.png" : "/weather-icons/a31c783-weather_icon_small_ic_clear_night3x.png";

Verified Weather Codes (Currently Available)

✅ API Verified: These weather codes have been tested and confirmed to work with the Tomorrow.io API as of June 2024.

Code	Description	Cloud Cover Range	Example Usage
1000	Clear	0-5%	Sunny, clear skies
1100	Mostly Clear	5-25%	Mostly sunny with few clouds
1101	Partly Cloudy	25-75%	Mix of sun and clouds
1102	Mostly Cloudy	75-95%	Mostly cloudy with little sun
1001	Cloudy	95-100%	Overcast, no sun visible
4001	Rain	Variable	Active precipitation
4000	Drizzle	Variable	Light precipitation, fine droplets
4200	Light Rain	Variable	Intermittent light rain showers

Real API Response Example

From a verified API call to New York location:

{
  "time": "2025-06-12T07:00:00Z",
  "values": {
    "weatherCode": 1100,
    "temperature": 22.1,
    "humidity": 65,
    "cloudCover": 13
  }
}

Complete Weather Codes Reference (Documentation Only)

📚 Reference Only: The codes below are from official Tomorrow.io documentation but many are not currently returned by the API. Use the verified codes section above for reliable API integration.

Below are the primary weather codes with their corresponding descriptions and icon references. Each code has day and night variants for appropriate visual representation.

Field Code	Description	Day/Night Variants
`weatherCode 1000` `weatherCodeFullDay 1000` `weatherCodeDay 10000` `weatherCodeNight 10001`	Clear	Day/Night: "Clear"
`weatherCode 1100` `weatherCodeFullDay 1100` `weatherCodeDay 11000` `weatherCodeNight 11001`	Mostly Clear	Consistent across day/night
`weatherCode 1101` `weatherCodeFullDay 1101` `weatherCodeDay 11010` `weatherCodeNight 11011`	Partly Cloudy	Consistent across day/night
`weatherCode 1102` `weatherCodeFullDay 1102` `weatherCodeDay 11020` `weatherCodeNight 11021`	Mostly Cloudy	Consistent across day/night
`weatherCode 1001` `weatherCodeFullDay 1001` `weatherCodeDay 10010` `weatherCodeNight 10011`	Cloudy	Same icon for day/night
`weatherCode 2100` `weatherCodeFullDay 2100` `weatherCodeDay 21000` `weatherCodeNight 21001`	Light Fog	Same icon for day/night
`weatherCode 2000` `weatherCodeFullDay 2000` `weatherCodeDay 20000` `weatherCodeNight 20001`	Fog	Same icon for day/night
`weatherCode 4000` `weatherCodeFullDay 4000` `weatherCodeDay 40000` `weatherCodeNight 40001`	Drizzle	Same icon for day/night
`weatherCode 4001` `weatherCodeFullDay 4001` `weatherCodeDay 40010` `weatherCodeNight 40011`	Rain	Same icon for day/night
`weatherCode 5000` `weatherCodeFullDay 5000` `weatherCodeDay 50000` `weatherCodeNight 50001`	Snow	Same icon for day/night
`weatherCode 8000` `weatherCodeFullDay 8000` `weatherCodeDay 80000` `weatherCodeNight 80001`	Thunderstorm	Same icon for day/night

Icon Reference: For the complete visual representation of these weather codes, including day and night icon variants, visit the official documentation which displays all weather condition icons.

Complete Basic Weather Codes List

The basic weatherCode field provides simple weather condition identifiers without mixed states. Use this for basic weather displays where you need straightforward condition descriptions.

Code	Description	Category
0	Unknown	Unknown
1000	Clear	Clear
1001	Cloudy	Clear
1100	Mostly Clear	Cloudy
1101	Partly Cloudy	Cloudy
1102	Mostly Cloudy	Cloudy
2000	Fog	Fog
2100	Light Fog	Fog
4000	Drizzle	Rain
4001	Rain	Rain
4200	Light Rain	Rain
4201	Heavy Rain	Rain
5000	Snow	Snow
5001	Flurries	Snow
5100	Light Snow	Snow
5101	Heavy Snow	Snow
6000	Freezing Drizzle	Freezing Rain
6001	Freezing Rain	Freezing Rain
6200	Light Freezing Drizzle	Freezing Rain
6201	Heavy Freezing Rain	Freezing Rain
7000	Ice Pellets	Ice Pellets
7101	Heavy Ice Pellets	Ice Pellets
7102	Light Ice Pellets	Ice Pellets
8000	Thunderstorm	Thunderstorm

Usage Example

{
  "weatherCode": 1101,
  "description": "Partly Cloudy"
}

Full Day Weather Codes

The weatherCodeFullDay provides the most comprehensive weather condition descriptions, including mixed conditions that combine multiple weather phenomena (calculated from sunrise to sunrise).

Mixed Conditions Example: Code 1103 represents "Partly Cloudy and Mostly Clear" - these combined conditions are only available in weatherCodeFullDay, weatherCodeDay, and weatherCodeNight fields, not in the basic weatherCode.

Mixed Condition Examples

Code	Mixed Condition Description	Icon
`1103`	Partly Cloudy and Mostly Clear
`4214`	Partly Cloudy and Light Rain
`5103`	Partly Cloudy and Light Snow
`8001`	Mostly Clear and Thunderstorm

Note: These mixed conditions demonstrate weather phenomena that occur simultaneously and are represented by specific codes in the extended weather code fields.

Sample Full Day Codes

Code	Description	Type
0	Unknown	Basic
1000	Clear	Basic
1001	Cloudy	Basic
1100	Mostly Clear	Basic
1101	Partly Cloudy	Basic
1102	Mostly Cloudy	Basic
1103	Partly Cloudy and Mostly Clear	Mixed Conditions
2000	Fog	Basic
2100	Light Fog	Basic
2101	Mostly Clear and Light Fog	Mixed Conditions
2102	Partly Cloudy and Light Fog	Mixed Conditions
2103	Mostly Cloudy and Light Fog	Mixed Conditions
2106	Mostly Clear and Fog	Mixed Conditions
2107	Partly Cloudy and Fog	Mixed Conditions
2108	Mostly Cloudy and Fog	Mixed Conditions
4000	Drizzle	Basic
4001	Rain	Basic
4200	Light Rain	Basic
4201	Heavy Rain	Basic
4202	Partly Cloudy and Heavy Rain	Mixed Conditions

Showing first 20 codes. Complete list contains 108 weather codes including all mixed conditions.

Usage Example

{
  "weatherCodeFullDay": 4214,
  "description": "Partly Cloudy and Light Rain"
}

Day and Night Specific Codes

⚠️ Not Currently Available: The day and night specific weather codes documented below are not returned by the API as of June 2024. Only the basic weatherCode field is available.

Separate weather codes for daytime and nighttime conditions would allow for more contextually appropriate weather descriptions and icon selection.

Day Weather Codes

Field: weatherCodeDay

Code	Description
0	Unknown
10000	Clear
10010	Cloudy
11000	Mostly Clear
11010	Partly Cloudy
11020	Mostly Cloudy
11030	Partly Cloudy and Mostly Clear
20000	Fog

Sample of 8 codes shown

Night Weather Codes

Field: weatherCodeNight

Code	Description
0	Unknown
10001	Clear
10011	Cloudy
11001	Mostly Clear
11011	Partly Cloudy
11021	Mostly Cloudy
11031	Partly Cloudy and Mostly Clear
20001	Fog

Sample of 8 codes shown

Day vs Night Code Patterns

Day Codes (Sunrise to Sunset)

• weatherCodeDay field
• Codes ending in 0 (e.g., 10000, 11000)
• Use "Clear" descriptions for clear conditions
• Solar-aware terminology
• Use sun-based weather icons

Night Codes (Sunset to Sunrise)

• weatherCodeNight field
• Codes ending in 1 (e.g., 10001, 11001)
• Use "Clear" instead of "Sunny"
• No solar-specific descriptions
• Use moon-based weather icons

Usage Example

{
  "weatherCodeDay": 10000,
  "weatherCodeNight": 10001,
  "dayDescription": "Clear",
  "nightDescription": "Clear"
}

Implementation Guide

Choosing the Right Weather Code Type

Use Basic Weather Code when:

• Building simple weather widgets
• Need minimal weather condition descriptions
• Working with limited display space
• Implementing basic weather alerts

Use Full Day Weather Code when:

• Need comprehensive weather descriptions
• Displaying detailed daily forecasts
• Building professional weather applications
• Mixed weather conditions are important

Use Day/Night Codes when:

• Time-specific weather icons are needed
• Building detailed hourly forecasts
• User interface changes based on time of day
• Solar context matters for your application

API Request Example

Include weather codes in your API request using the fields parameter:

cURL CommandBASH
curl "https://api.tomorrow.io/v4/weather/forecast?location=40.7128,-74.0060&fields=weatherCode,temperature,humidity&apikey=YOUR_API_KEY"

Actual API Response Structure

Based on real API testing as of June 2024:

{
  "timelines": {
    "hourly": [
      {
        "time": "2025-06-12T07:00:00Z",
        "values": {
          "weatherCode": 1100,
          "temperature": 22.1,
          "humidity": 65
        }
      },
      {
        "time": "2025-06-12T08:00:00Z",
        "values": {
          "weatherCode": 1102,
          "temperature": 26,
          "humidity": 53
        }
      }
    ]
  }
}

License & Attribution

Weather Icons Usage Requirements

The Tomorrow.io weather icons are provided under the CC BY 4.0 License and require proper attribution.

Required Attribution:

"Powered by Tomorrow.io"

Place this attribution visibly in your application when using Tomorrow.io weather icons. For more details, see the official repository.