OpenWeatherMap Integration Documentation

Overview

The OpenWeatherMap integration allows users to fetch current weather data, 5-day weather forecasts, and air pollution data through the OpenWeatherMap API. This integration is designed to work seamlessly with Vantage, enabling users to enhance their applications or analytics platforms with real-time weather information relevant to specific geolocations.

Key Features

• Retrieve current weather conditions using latitude/longitude, zip code, or city queries.
• Access 5-day weather forecasts.
• Obtain air quality data based on geographic coordinates.

Settings

1. API Key

• Input Type: String
• Description: This is the user-specific API key required to authenticate requests to the OpenWeatherMap API. It is essential for all API interactions.
• Default Value: None (must be provided by the user)

2. Location Parameters

Various parameters can be used for specifying a location to get weather information:

• Latitude (lat)

  • Input Type: Numeric
  • Description: Specifies the latitude of the location for which to retrieve weather data. It must be provided together with the longitude.
  • Default Value: None

• Longitude (lon)

  • Input Type: Numeric
  • Description: Specifies the longitude of the location for which to retrieve weather data. It must be provided together with the latitude.
  • Default Value: None

• Zip Code (zip)

  • Input Type: String
  • Description: Represents the postal code of the location for which to obtain weather information. If provided, it takes precedence over latitude and longitude.
  • Default Value: None

• City Query (q)

  • Input Type: String
  • Description: A generic city name query to retrieve weather data. If this is provided and no latitude/longitude or zip code is specified, it will be used to search for the weather information.
  • Default Value: "Lenexa,KS,US" (fallback if no other location parameters are provided)

3. Units

• Input Type: Dropdown (Options: metric, imperial, standard)
• Description: Defines the unit system for the returned data. Changing this setting affects how temperature and other measurement data are presented.
• Default Value: "metric" (temperature in Celsius, wind speed in meter/sec)

How It Works

The OpenWeatherMap integration utilizes methods to fetch weather data based on the specified location and parameters. Each method constructs a request to the OpenWeatherMap API, appending necessary parameters and the API key for authentication.

Method Descriptions

• getCurrentWeather({ lat, lon, zip, q, units })

  • Fetches the current weather information for the specified location.

• get5DayForecast({ lat, lon, zip, q, units })

  • Retrieves a 5-day weather forecast including daily temperature, wind speed, and conditions.

• getAirPollution({ lat, lon })

  • Returns air pollution details for a given latitude and longitude. Note that only latitude and longitude can be used for this request.

Data Expectations

The integration expects the following data for effective functioning:

• An active API key from OpenWeatherMap.
• Valid geolocation data (latitude and longitude, zip code, or city name).
• Desired units for measurement (metric, imperial, or standard).
• Additional parameters, such as specific queries, when using city names.

Use Cases & Examples

Use Case 1: Weather-Dependent Application

A travel planning application needs to provide users with current weather conditions at their destination to suggest packing lists and activities.

Use Case 2: Environmental Monitoring

A sustainability dashboard tracks air quality based on real-time data to inform users about pollution levels in their vicinity, facilitating informed decision-making for outdoor activities.

Use Case 3: Agriculture Planning

Farmers could use this integration to receive weather forecasts and updates about air quality, assisting them in making timely decisions regarding planting, harvesting, and protecting crops.

Example Configuration

To implement the integration for a travel planning tool, consider configuring the following settings:

{
    "apiKey": "YOUR_API_KEY_HERE",
    "lat": 34.0522,
    "lon": -118.2437,
    "units": "imperial"
}

With the above configuration, the integration will fetch current weather data for Los Angeles, California, using Fahrenheit for temperature measurements, which is suitable for the target audience of U.S. travelers.

This will allow the users to plan their trips effectively, making informed choices based on the real-time weather conditions.