Working with HERE Weather API V3

Working with HERE Weather API V3

It's been a while since HERE Destination Weather API was last explored, and with the unusually warm weather here in Riga, Latvia, now is the perfect time to dive into what the updated Weather API V3 offers and explore its potential applications.

HERE Destination Weather is tailored for various industries, including:

Automotive: Enhance in-car navigation systems with real-time weather updates.

Truck and Fleet Operations: Support logistics and route planning with accurate weather data.

App Developers: Build innovative applications using HERE’s comprehensive weather services.

The API provides a wide range of capabilities, including:

Daily Forecasts: Up to 7 days.

Hourly Forecasts: Up to 48 hours.

Weather Alerts: For the next 24 hours, either at a specific location or along a route.

Precipitation Maps: Recent, current, and 48-hour forecast precipitation images.

Astronomical Data: Sunrise, sunset, moonrise, and moonset times.

The API is available in two feature levels:

Base Offering (Standard Features):Includes essential weather data for typical use cases.

Premium Offering: Includes all standard features plus advanced capabilities.

Note: Premium features require a request for grant access. Contact us to enable them for your client ID, therefore, for this tutorial, we’ll focus exclusively on standard features.

Project Prerequisites

To build a Simple Weather Report for Riga, Latvia, you'll need a few essential items. These tools and resources will help you fetch weather data and display it effectively:

API Key: Required to authenticate requests to HERE Weather API V3.
Mapping Library: I’m using the HERE Maps API for JavaScript to visualize the data.
HERE Weather API V3 Access: Use the API documentation to construct your requests. You can find the guide here: HERE Weather API V3 Documentation.

Once you have these prerequisites in place, you’ll be ready to start building your weather report.

Step 1: Verify Your API Key

Before we dive into building the weather application, it’s important to verify that the API key works and to understand the data the API returns. This step involves sending a request to the HERE Weather API to retrieve an observation report and reviewing the response.

Testing the API in Your Browser

You can quickly check the API’s response by constructing a request URL and pasting it into your browser. The response will be in JSON format and can be reviewed directly in the browser. Here’s a sample request URL:

https://weather.hereapi.com/v3/report?products=observation&q=Riga,Latvia&apiKey=WEATHER_API_KEY

The returned JSON result will include observation data for Riga, Latvia. Note that the data may vary depending on when the request is made, as weather information is constantly updated.

Example Response:

To make the JSON response easier to interact with, I prefer viewing it in the console logs. However, feel free to use the browser response or any JSON viewer you prefer.

Key Request Parameters

When constructing your API request, the following parameters are essential:

Base URL: The endpoint for the HERE Weather API.

Path: Specifies the type of weather report.

Resource: Defines the product, such as observation or forecast data.

API Key: Used to authenticate your request.

Understanding API Products

The HERE Weather API provides multiple data layers. For this example, we’ll focus on the “observation” layer, but keep in mind that the API supports the following products:

"observation"

"forecast7days"

"forecast7daysSimple"

"forecastHourly"

"forecastAstronomy"

"alerts"

"nwsAlerts"

The specific structure of responses for each product and parameter descriptions can be reviewed in the API Reference documentation: HERE Weather API V3 API Reference.

Additional Query Parameters

When constructing your API request, you can customize it using these optional query parameters:

Parameter	Description	Example
products	Identifies the type of report to obtain. Comma-separated values are supported.	"observation,forecastHourly"
q	Enter a free-text query for a location.	"Riga, Latvia"
zipCode	ZIP code of the location (only for U.S. locations).	"90210"
location	Specifies a geographical location in WGS-84 format.	"52.5251,13.3694"
units	Units of measurement: metric (default) or imperial.	"metric"
lang	Defines the language of the response.	"en-US"
politicalView	Specifies a political view for territories with unresolved claims (e.g., "CHN").	"CHN"
hourlyDate	Date for which hourly forecasts are to be retrieved.	"2025-01-22"

NB! Try fetching comma separated products like "observation,forecastHourly" and check the response.

Now that we understand how to test and construct requests, we can analyze the response structure in detail before setting up the React project.

Step 2: Set Up the Project

In this step, we’ll set up a Vite React application to build a sample weather application with visual representations.

Initialize the React Project

To get started, follow the official tutorial for setting up a React project using HERE Maps API for JavaScript: HERE Maps API React Practices.

Run the following command to initialize the project with Vite:

Copied

        npm create vite@latest weather-app --template react 

cd weather-app 

npm install 

npm run dev

Install TanStackQuery

To fetch weather data efficiently, I’m using TanStackQuery. If you’d like to use it as well, follow the installation instructions here: TanStackQuery React Installation. Honestly, I have fallen in love with the functionality and developer experience it provides. I will definitely use it more in my future projects.

Here’s a simplified structure of App.jsx:

Copied

        function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div className="App">
        <WeatherComponent />
      </div>
      <ReactQueryDevtools initialIsOpen={false}></ReactQueryDevtools>
    </QueryClientProvider>
  );
}

In this structure, the WeatherComponent handles fetching the weather data and passing it to the Map component for rendering.

Fetch and Render Weather Data

In the WeatherComponent I fetch the weather observation data and use it to create visual markers on the map.

Copied

        export function useWeatherStandart(queryKey: string) {
  return useQuery({
    queryFn: async () => {
      const res = await fetch(
        `https://weather.hereapi.com/v3/report?products=${queryKey}&q=Riga,Latvia&apiKey=${
          import.meta.env.VITE_WEATHER_API_KEY
        }`
      );
      const data = res.json();
      return data;
    },
    queryKey: [queryKey],
  });
}

GlobalLoadingIndicator component that is responsible of visually showing if something is being fetched
NavBar is the component that controls the layer visibility
Map a component responsible for creating a basemap and building layers as well as returns a callback from the icons layer for the tooltip
Panel to display the map tooltip information

Copied

          <>
      <GlobalLoadingIndicator />
      <NavBar onChange={(e) => setCheckBoxObj(e)} />
      <Map
        coordinates={latviaBbox}
        center={latviaCenter}
        requestParams={checkBoxObj}
        layers={!isLoadingObservation && observation.places}
        setSelectedMarkerData={setSelectedMarkerData}
      />
      <Panel
        content={{
          places: selectedMarkerData || [], // Fallback to empty array if places is undefined
          url: `https://weather.hereapi.com/v3/report?products=observation&q=Riga,Latvia&apiKey=WEATHER_API_KEY`,
        }}
      />
    </>

These are the key steps to create markers from the observations:

Create a Layer for Weather Data

Copied

        const weatherLayer = new H.map.Group();

Loop Through Observation Data
The data returned from the API contains an array of weather observations. For each observation, create a map icon and marker. In my case I create H.map.DomMarker as I am plotting html elements from our own storybook. For simple markers use H.map.Marker instead

Copied

          icons?.observations?.forEach((icon: Icon) => {
    // Use the place-specific icon link or fallback to the default
    const weather_icon_link = icon?.iconLink || defaultIconUrl;
    const element = iconDOMElementFactory(weather_icon_link, icon.temperature);

    // Create a text label using a DOM overlay
    const weatherMarkerChip = new H.map.DomMarker(
      { lat: icon.place.location.lat, lng: icon.place.location.lng },
      {
        icon: new H.map.DomIcon(element, {
          onAttach: (clonedElement: any, domIcon: any, domMarker: any) => {
            clonedElement.addEventListener("mousemove", () => {
              // DO SOMETHING HERE

              setSelectedMarkerData(domMarker.getData());
          });
          },

        }),
    
        data: icon,
      }
    );
       // Add the marker group to the layer
    observationsLayer.addObject(weatherMarkerChip);
  });

Add the Layer to the Map
After creating all the markers, add the group of weather icons to the map. In the Map.tsx once the map is initialized (MapRef.current is true and there are layers passed to the component) we can build the layer and plot it.

Note that map.removeObjects(map.getObjects()); removes every layer from the map and then afterwards map.addObject(observationsLayer); puts them back ensuring the markers are correctly repopulated.

Copied

          useEffect(() => {
    if (mapRef.current && layers) {
      const map = mapRef.current;
      const observationsLayer = new H.map.Group();

      if (layers[0]) {
        const icons = layers[0];
        addObservations(icons, observationsLayer, setSelectedMarkerData);
      }

      map.removeObjects(map.getObjects());
      

// requestParams is a checkbox from the panel, if checked then true
      if (requestParams.observation) {
        map.addObject(observationsLayer);
      }
    }
  }, [mapRef, layers, requestParams]);

Conclusion

And that’s how the weather in Riga, Latvia looks today—visually represented using HERE Weather API V3 and the HERE Maps platform. Through this project, we explored how to fetch weather data, process it, and render it dynamically on a map with React.