Clear Weather API

Clear Weather API is a wrapper for OpenWeather Map API, designed to simplify the process of fetching and handling weather data. With an easy-to-use interface, this package offers premium features such as data transformation for more human-readable output, caching to avoid rate limits, and a choice between animated and static weather icons. Clear Weather API also includes types for all weather data, ensuring a smooth and efficient app development experience.

Open Weather Map API's supported

• One Call API
• Current Weather Data
• Hourly Forecast 4 Days
• Daily Forecast 16 Days
• Climatic Forecast 30 days
• 5 Day / 3 Hour Forecast

Features

• Data Transformation (Premium)
• Avoid hitting rate limits with Caching (Premium)
• Cool Weather Icons (Premium)
• Types for all weather data
• Limit errors with types for all weather data
• Smooth and easy development experience

Getting Started

To use this library, you need an Open Weather Map API key. Sign up at Open Weather Map and activate the APIs you'd like to use by visiting the Open Weather Map API page.

API Documentation

API documentation is coming soon at docs.clearweatherapi.com.

Installation

To install the package, use the following command:

npm install clearweatherapi

or

yarn add clearweatherapi

Usage

To use the package in your project, first include it and then pass in your Open Weather Map API key, Clear Weather API user ID, coordinates, and optional units and language.

Example

THis package supports both ES6 and CommonJS imports.

import ClearWeatherAPI from 'clearweatherapi';
// or
const ClearWeatherAPI = require('clearweatherapi');

const weather = new ClearWeatherAPI({
  userId: 'YOUR-CLEARWEATHERAPI-USERID',
  openWeatherApiKey: 'YOUR_OPENWEATHER_API_KEY',
  coords: {
    latitude: '34',
    longitude: '-118',
  },
  units: 'metric',
  lang: 'en',
});
// Forecast example
const forecast = weather.forecast({
  cache: true,
  cacheKey: 'YOUR_CACHE_KEY',
  access: 'premium',
});

const climatic30Day = await forecast.climatic30Day(26);
const daily16 = await forecast.daily16(17);
const daily5 = await forecast.fiveDay3Hour(2);
const hourly4Days = await forecast.hourly4Days(5);

// One Call example
const oneCall = weather.oneCall({
  cache: false,
  cacheKey: 'YOUR_CACHE_KEY',
  access: 'premium',
  version: '3.0',
});

const current = await oneCall.current();
const hourly = await oneCall.hourly();
const daily = await oneCall.daily();
const minutely = await oneCall.minutely();
const alerts = await oneCall.alerts();
// all method accepts a string or array of strings with the data to exclude
const all = await oneCall.all(['minutely']);

// Current Weather data
const currentWeather = await weather.currentWeather({
  cache: false,
  cacheKey: 'YOUR_CACHE_KEY',
  access: 'premium',
});

Global Options

| Option | Type | Required | Description | | ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- | | userId | string | Yes | Your Clear Weather API user ID | | openWeatherApiKey | string | Yes | Your OpenWeather Map API key | | coords | object | Yes | An object containing the latitude and longitude of the location for which you want to fetch weather data | | units | string | No | The unit system to use (default: 'metric') | | lang | string | No | The language for the weather data (default: 'en') |

Forecast Object Options

| Option | Type | Required | Description | | -------- | ------- | -------- | ---------------------------------------------------------------------------- | | cache | boolean | No | Enable or disable caching (default: false, available only for premium users) | | cacheKey | string | No | The key to use for caching, this can only be used when cache is true | | access | string | Yes | The access type for the API ('free' or 'premium') |

The forecast methods allow you to retrieve weather forecasts for the specified location with different time frames and intervals. Each method takes a parameter that represents the count of data points or days you want to retrieve forecast data for. This flexibility enables you to get customized forecasts based on your specific requirements. The available forecast methods are:

• forecast.climatic30Day(count): Fetches a 30-day climatic forecast.
• forecast.daily16(count): Retrieves a daily forecast for up to 16 days.
• forecast.fiveDay3Hour(count): Provides a 5-day forecast with 3-hour intervals.
• forecast.hourly4Days(count): Obtains an hourly forecast for up to 4 days.

Current Weather Object Options

| Option | Type | Required | Description | | -------- | ------- | -------- | ---------------------------------------------------------------------------- | | cache | boolean | No | Enable or disable caching (default: false, available only for premium users) | | cacheKey | string | No | The key to use for caching, this can only be used when cache is true | | access | string | Yes | The access type for the API ('free' or 'premium') | | |

One Call Object Options

| Option | Type | Required | Description | | -------- | ------------ | -------- | ----------------------------------------------------------------------------------------------- | | cache | boolean | No | Enable or disable caching (default: false, available only for premium users) | | cacheKey | string | No | The key to use for caching, this can only be used when cache is true | | access | string | Yes | The access type for the API ('free' or 'premium') | | exclude | array/string | No | Data to exclude from the response (options: 'current', 'hourly', 'daily', 'minutely', 'alerts') | | version | string | No | The version of the One Call API to use (default: '3.0') |

oneCall.all() method accepts a string or array of strings with the data to exclude

const all = await oneCall.all(['minutely']);

Icons

Icons are available for premium users and can be found in each weather data object. The icons are provided in the following format:

const weatherData = {
  // ...
  icons: {
    static: 'iconUrl',
    animated: 'iconUrl',
  },
  // ...
};

License

This project is licensed under the MIT License.