openweathermap-ts

An abstract layer over openWeatherMap APIs to simplify making calls. Built with TypeScript and Promises. Even the returned JSON responses are typed for your benefits!

Note: The library currently only supports free tier API services:

• Current Weather
• 3-hour Forecast. (5 day / 3 hour)

Installation

// install using npm
npm install openweathermap-ts

You will also need to register for an API key at the official site.

Basic Setup

const OpenWeatherMap = require('openweathermap-ts');
// or
import OpenWeatherMap from 'openweathermap-ts';

const openWeather = new OpenWeatherMap({
  apiKey: 'Your API Key'
});

Usage

There are 2 ways of using public getter methods.

1. Pass in argument/s
2. Store preferences in the location object

When both are used, the argument/s precede over the defined location object.

Notice some methods are grouped together with & because their arguments are the same. But they produce different results.

getCurrentWeatherByCityName & getThreeHourForecastByCityName

/**
 * @param {
 *  cityName: string,
 *  state?: string, // Spell it out. E.g, Texas
 *  countryCode?: CountryCodeType
 * }
 */
openWeather
  .getCurrentWeatherByCityName({
    cityName: 'Cedar Park'
  })
  .then((weather) => console.log('Weather object is', weather));

// or async await example
try {
  const weather = await openWeather.getThreeHourForecastByCityName({
    cityName: 'Cedar Park',
    state: 'Texas',
    countryCode: 'US'
  });
  console.log('Weather object is', weather);
} catch (error) {
  console.error('Error is ', error);
}

List of ISO 3166 CountryCodeType

getCurrentWeatherByCityId & getThreeHourForecastByCityId

/**
 * @param cityId: number
 */
openWeather
  .getCurrentWeatherByCityId(1835848)
  .then((weather) => {
    console.log('Weather object is', weather);
  })
  .catch((error) => console.error('Error is ', error));

Or

// set the cityId in location object
openWeather.setCityId(1835848);

// invoke the method without an argument
openWeather
  .getThreeHourForecastByCityId()
  .then((weather) => {
    console.log('Weather object is', weather);
  })
  .catch((error) => console.error('Error is ', error));

List of CityIds

getCurrentWeatherByGeoCoordinates & getThreeHourForecastByGeoCoordinates

/**
 * @params latitude: number, longitude: number
 */
openWeather
  .getCurrentWeatherByGeoCoordinates(33.426971, -117.611992)
  .then((weather) => console.log('Weather object is', weather));

getCurrentWeatherByZipcode & getThreeHourForecastByZipcode

/**
 * @params zipcode: number, countryCode?: CountryCodeType
 */
openWeather
  .getCurrentWeatherByZipcode(84604)
  .then((data) => console.log('Weather object is', data));

Or

openWeather
  .getCurrentWeatherByZipcode(84604, 'US')
  .then((data) => console.log('Weather object is', data));

List of CountryCodeType

Config Methods

Helpers for settings object

/**
 * @param apiKey: string
 */
openWeather.setApiKey('yourApiKey');

/**
 * @param units: 'imperial'| 'metric' | 'standard' (Kelvin)
 */
openWeather.setUnits('metric');

/**
 * @param language: LanguageTypes
 */
openWeather.setLanguage('kr');
// LanguageTypes List -> https://github.com/shimphillip/openweathermap-ts/blob/master/languages.md

/**
 * @param none
 */
openWeather.getAllSettings();

/**
 * @param none
 */
openWeather.clearSettings(); // Remember to reset your API Key

Helpers for location object

/**
 * @param cityId: number
 */
openWeather.setCityId(1835848);

/**
 * @param {
 *  cityName: string,
 *  state?: string, // (optional) Spell it out. E.g, Texas
 *  countryCode?: CountryCodeTypes // (optional)
 * }
 */
openWeather.setCityName({
  cityName: 'Austin'
});
// List of CountryCodeTypes https://github.com/shimphillip/openweathermap-ts/blob/master/src/helpers/country-codes.ts

/**
 * @params latitude: number, longitude: number
 */
openWeather.setGeoCoordinates(33.426971, -117.611992);

/**
 * @params zipcode: number, countryCodeTypes?: string (optional)
 */
openWeather.setZipCode(84604, 'US');
// List of CountryCodeType https://github.com/shimphillip/openweathermap-ts/blob/master/src/helpers/country-codes.ts

/**
 * @param none
 */
openWeather.getAllLocations();

/**
 * @param none
 */
openWeather.clearLocation();

Official API Docs

Current Weather API: https://openweathermap.org/current 5 day / 3 hour Forecast API: https://openweathermap.org/forecast5

Bug Reports

Please create issues or pull requests at https://github.com/shimphillip/openweathermap-ts

Future Works 🚀

• CityID validations
• Filter out unsolicited information options
• Handle coordinate types
• Supports other formats like XML
• Enforce strict rules on countryCodes and states
• support for paid services like Daily Forecast and Hourly Forecast

Love what you use? Buy me a ~~coffee~~ boba!🍹