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-tsYou 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.
- Pass in argument/s
- 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!
