Skip to content

Endunry/openweathermap-ts

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

openweathermap-ts

Build Status npm version Donate

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!๐Ÿน

Buy Me A Coffee