Defining the icon set in the Weather API

July 7, 2026

The Visual Crossing Timeline Weather API can return an icon value for each daily, hourly, and current-conditions weather record. This value provides a simple, high-level summary of the weather during that period.

Example icon values include:

rain
snow
fog
cloudy
partly-cloudy-day
clear-night

The icon field contains a text identifier. It does not contain an image, image URL, or graphical icon. Your application can map the returned identifier to a PNG or SVG image, a CSS class, an icon library, or your own custom artwork.

Choosing an icon set

Use the optional iconSet request parameter to select the set of icon identifiers returned by the API.

The Timeline Weather API currently supports two icon sets:

`iconSet` value	Description
`icons1`	The default icon set, providing broad weather classifications such as snow, rain, fog, wind, cloudy, partly cloudy, and clear
`icons2`	An expanded icon set that adds distinctions for showers, snow showers, and thunderstorms

If you do not include the iconSet parameter, the Timeline Weather API uses icons1.

The legacy forecast and history Weather API endpoints support only icons1.

Example API request

The following request selects the expanded icons2 set:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?unitGroup=metric&iconSet=icons2&key=YOUR_API_KEY

A returned daily or hourly weather record may then contain an icon value such as:

{
  "datetime": "2026-07-23T15:00:00",
  "temp": 21.4,
  "conditions": "Rain, Partially cloudy",
  "icon": "showers-day"
}

The value showers-day is a lookup key that your application can associate with the appropriate image or other visual treatment.

You can limit the response to the fields required by your application by using the elements parameter:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timeline/London,UK?unitGroup=metric&iconSet=icons2&elements=datetime,temp,conditions,icon&key=YOUR_API_KEY

How the API selects an icon

Each weather record contains one icon value.

Weather conditions are not returned as a combination of multiple icon IDs. When more than one condition applies, the API evaluates the applicable conditions in priority order and returns the highest-priority matching icon.

For example, snow has a higher priority than cloudiness. If a period contains snow and is also cloudy, the API returns the snow icon rather than the cloudy icon.

The icon tables below are listed in descending priority order. An icon near the top of a table takes precedence over an icon below it when both conditions apply.

The icon field is intended as a concise visual summary. Applications that require more detail should also inspect the underlying weather elements, such as:

precip
preciptype
snow
windspeed
visibility
cloudcover
conditions

Day and night icons

Some icon IDs have separate day and night variants, such as:

partly-cloudy-day
partly-cloudy-night
clear-day
clear-night

When a condition has day and night variants, the API compares the time of the weather record with the local sunrise and sunset times for that location and date.

A daytime record uses the -day variant, while a nighttime record uses the corresponding -night variant.

Daily records summarize an entire day, so the icon generally represents the dominant or most significant conditions for that daily period.

`icons1`: default icon set

The icons1 set provides a compact set of broad weather classifications. It is the default for the Timeline Weather API and is the only icon set available from the legacy forecast and history endpoints.

The icons are shown below in descending priority order.

Icon ID	General selection rule
`snow`	The amount of snow is greater than zero
`rain`	The amount of rainfall is greater than zero
`fog`	Visibility is low
`wind`	Wind speed is high
`cloudy`	Cloud cover is greater than 90%
`partly-cloudy-day`	Cloud cover is greater than 20% during daytime
`partly-cloudy-night`	Cloud cover is greater than 20% during nighttime
`clear-day`	Cloud cover is less than 20% during daytime
`clear-night`	Cloud cover is less than 20% during nighttime

Because the rules are evaluated in priority order, precipitation takes precedence over fog, wind, and cloud-cover classifications.

For example, a windy and cloudy period containing rain will normally receive the rain icon because rain appears above wind and cloudiness in the priority order.

`icons2`: expanded icon set

The icons2 set provides more detailed precipitation classifications. In particular, it can distinguish persistent precipitation from showers and can identify thunderstorm conditions.

The icons are shown below in descending priority order.

Icon ID	General selection rule
`snow`	Snow occurs throughout the period or the amount of snow is greater than zero
`snow-showers-day`	Periods of snow or snow showers occur during daytime
`snow-showers-night`	Periods of snow or snow showers occur during nighttime
`thunder-rain`	Thunderstorms and rain occur throughout the period
`thunder-showers-day`	Possible or intermittent thunderstorms occur during daytime
`thunder-showers-night`	Possible or intermittent thunderstorms occur during nighttime
`rain`	Rain occurs throughout the period or the amount of rainfall is greater than zero
`showers-day`	Periods of rain or rain showers occur during daytime
`showers-night`	Periods of rain or rain showers occur during nighttime
`fog`	Visibility is low
`wind`	Wind speed is high
`cloudy`	Cloud cover is greater than 90%
`partly-cloudy-day`	Cloud cover is greater than 20% during daytime
`partly-cloudy-night`	Cloud cover is greater than 20% during nighttime
`clear-day`	Cloud cover is less than 20% during daytime
`clear-night`	Cloud cover is less than 20% during nighttime

Use icons2 when your interface would benefit from distinguishing showers from more persistent precipitation or from identifying thunderstorm conditions separately.

Use icons1 when you need a smaller and simpler set of general-purpose weather icons.

Icon values compared with weather conditions

The icon and conditions fields serve related but different purposes.

The icon field provides a single machine-readable identifier intended primarily for visual presentation:

"icon": "partly-cloudy-day"

The conditions field provides a human-readable description and may include more than one applicable condition:

"conditions": "Rain, Partially cloudy"

A record can therefore describe several simultaneous conditions while still returning only one icon ID. The selected icon represents the highest-priority or most useful visual summary of that weather period.

For detailed application logic, use the individual weather elements rather than relying only on the icon value.

For example, use:

precip and preciptype to evaluate precipitation;
snow and snowdepth to evaluate snowfall and accumulated snow;
windspeed and windgust to evaluate wind;
visibility to evaluate restricted visibility;
cloudcover to evaluate cloud coverage.

The icon should generally be treated as a presentation value rather than a replacement for the underlying weather data.

Mapping icon IDs to images

Because the API returns a text identifier, your application controls how each icon is displayed.

For example, an application could construct an image filename from the returned value:

const iconId = weatherRecord.icon;
const iconUrl = `/weather-icons/${iconId}.svg`;

If the API returns:

partly-cloudy-day

the application would load:

/weather-icons/partly-cloudy-day.svg

A simple HTML implementation might look like this:

<img
  src="/weather-icons/partly-cloudy-day.svg"
  alt="Partly cloudy"
>

In a real application, use the returned icon value dynamically and use the conditions field or another suitable description for accessible alternative text.

You can also map icon IDs to CSS classes:

const iconClass = `weather-icon weather-icon-${weatherRecord.icon}`;

Or map them to components in a framework:

const iconComponents = {
  "clear-day": ClearDayIcon,
  "clear-night": ClearNightIcon,
  "partly-cloudy-day": PartlyCloudyDayIcon,
  "partly-cloudy-night": PartlyCloudyNightIcon,
  "cloudy": CloudyIcon,
  "rain": RainIcon,
  "snow": SnowIcon,
  "fog": FogIcon,
  "wind": WindIcon
};

const IconComponent = iconComponents[weatherRecord.icon];

When using icons2, include mappings for the additional shower and thunderstorm identifiers.

Sample Visual Crossing weather icons

Visual Crossing provides a sample weather icon collection with filenames that match the icon IDs returned by the API.

The collection includes icon previews and source files in PNG and SVG formats. You can use these icons directly or use them as a reference when creating an icon set that matches your application’s design.

The sample icons are available from the Visual Crossing Weather Icons repository on GitHub:

https://github.com/visualcrossing/WeatherIcons

For example, artwork representing clear-day should use a filename such as:

clear-day.svg

Similarly, the expanded icon set can use filenames such as:

showers-day.svg
thunder-showers-night.svg
snow-showers-day.svg

Keeping your filenames aligned with the API values avoids the need for an additional translation layer.

Creating your own icon set

You are not required to use the sample Visual Crossing artwork. You can create custom icons that match your application’s branding, color scheme, visual style, and accessibility requirements.

Your custom artwork should provide a matching asset for every icon ID that your selected icon set may return.

For icons1, provide assets for:

snow
rain
fog
wind
cloudy
partly-cloudy-day
partly-cloudy-night
clear-day
clear-night

For icons2, also provide assets for:

snow-showers-day
snow-showers-night
thunder-rain
thunder-showers-day
thunder-showers-night
showers-day
showers-night

Applications should also provide a fallback icon in case they encounter an unexpected or newly introduced value:

const iconUrl = knownIcons.includes(weatherRecord.icon)
  ? `/weather-icons/${weatherRecord.icon}.svg`
  : "/weather-icons/unknown.svg";

Visual Crossing may extend the available icon sets over time, so a fallback helps make your application more resilient.

Implementation recommendations

When adding weather icons to an application:

Select icons1 or icons2 explicitly if your application depends on a particular set of values.
Create a mapping for every icon ID supported by that set.
Include a fallback for unknown or missing icon values.
Use the conditions field for user-facing descriptions or accessible alternative text.
Use the underlying numerical weather elements for alerts, calculations, and business rules.
Do not assume that the icon represents every condition occurring during the period.
Remember that day and night icon variants are selected using the location’s local sunrise and sunset times.

Summary

The Weather API icon field gives applications a simple way to present weather conditions visually.

Each weather record returns one icon ID, selected according to a priority order. The identifier acts as a lookup key for artwork or UI components rather than as an image itself.

Use:

icons1 for a compact set of broad weather classifications;
icons2 for additional distinctions between persistent precipitation, showers, snow showers, and thunderstorms.

For more detailed weather analysis, use the conditions field and the underlying numerical weather elements alongside the icon value.

Questions or need help?

Our AI Code generator provides real-time, 24×7 access to code generation and other questions related to the Weather API usage.

For questions about the icon field, the iconSet parameter, or implementing weather icons in your application, visit the actively monitored Visual Crossing support forum or contact Visual Crossing Support.