Custom Icon Mapping

Use cases where custom icon mapping is required can use the API's weatherCodedPrimary values seen in the Coded Weather docs. These values correlate with the [weather] code which can be either Cloud Codes or Weather Codes. Alternatively, you can use the icon value to map directly to custom icons. You can review full list of icons used by the API. There are 3 main ways to go about this listed below.

Icon Matching

This method will be the easiest to integrate. Copy the list of icon names and create your own icons for each of these icons. Within the /observations and /forecasts endpoints you will see these icon values stored in the icon attribute.

Using regular expressions

Using regular expressions you can map several different icon names from the API response to a single icon. This eliminates the need to have different icons for very similar weather conditions.

For example, sleet and freezing rain are very similar weather conditions so we can just use the same icon. Additionally, it is important to note many icons may either have a sun or moon in the image depending on the time of day. Using regex we can easily identify when to use a nighttime icon as the API will append the letter n to the nighttime icon. Contrary to the sun/moon icons, some icons do not need to distinguish between night and day, such as thunderstorms.

Our WeatherBlox library is currently using a similar method (opens in a new tab) for displaying icons.

Mapping weather codes

This method provides the most control over your icon display and gives you the ability to customize weather phrases. Customizing weather phrases also allows you to translate these phrases into localized languages.

Reviewing the coded weather information, the format for weather codes is [coverage]:[intensity]:[weather]. Using the logic outlined on the Coded Weather page, you can capture all of the potential outcomes and display specific icons based on the weather code.

We suggest utilizing the weatherCodedPrimary value in the /observations and /forecasts endpoints as this will be the main weather event/condition. The logic here could either parse the [weather] portion of the code, or gather the entire code to produce a custom message and/or map it to an icon.