https://github.com/purinton/openweathermap
A simple, modern, Node.js client for the OpenWeatherMap API. Fetch current weather, 24-hour forecast, and sunrise/sunset times with a clean, promise-based API.
https://github.com/purinton/openweathermap
api esm forecast nodejs openweathermap openweathermap-api sunrise sunset typescript weather
Last synced: 3 months ago
JSON representation
A simple, modern, Node.js client for the OpenWeatherMap API. Fetch current weather, 24-hour forecast, and sunrise/sunset times with a clean, promise-based API.
- Host: GitHub
- URL: https://github.com/purinton/openweathermap
- Owner: purinton
- License: mit
- Created: 2025-06-17T15:46:22.000Z (4 months ago)
- Default Branch: master
- Last Pushed: 2025-07-11T15:42:13.000Z (3 months ago)
- Last Synced: 2025-07-11T16:10:12.593Z (3 months ago)
- Topics: api, esm, forecast, nodejs, openweathermap, openweathermap-api, sunrise, sunset, typescript, weather
- Language: JavaScript
- Homepage: https://discord.gg/QSBxQnX7PF
- Size: 195 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [](https://discord.gg/QSBxQnX7PF)
## @purinton/openweathermap [](https://www.npmjs.com/package/@purinton/openweathermap)[](LICENSE)[](https://github.com/purinton/openweathermap/actions)
> A simple, modern, Node.js client for the OpenWeatherMap API. Fetch current weather, 24-hour forecast, and sunrise/sunset times with a clean, promise-based API.
---
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [TypeScript](#typescript)
- [License](#license)
## Features
- Fetch current weather for any coordinates
- Fetch 24-hour forecast (3-hour intervals)
- Fetch sunrise and sunset times (adjusted to local timezone)
- Fully typed (TypeScript definitions included)
- Supports dependency injection for fetch and API key (easy to test/mocks)
## Installation
```bash
npm install @purinton/openweathermap
```
## Usage
```js
import { getCurrent, get24hForecast, getSun } from '@purinton/openweathermap';
const lat = 40.7128;
const lon = -74.0060;
const apiKey = 'your_api_key_here';
(async () => {
const current = await getCurrent(lat, lon, { apiKey, units: 'F' });
console.log('Current:', current);
const forecast = await get24hForecast(lat, lon, { apiKey, units: 'F' });
console.log('24h Forecast:', forecast);
const sun = await getSun(lat, lon, { apiKey, units: 'F' });
console.log('Sunrise/Sunset:', sun);
})();
```
## API
### getCurrent(lat, lon, options?)
Fetches current weather for the given latitude and longitude.
- `lat` (number): Latitude
- `lon` (number): Longitude
- `options` (object):
- `apiKey` (string, required): Your OpenWeatherMap API key
- `units` (string, optional): 'F' for Fahrenheit, 'C' for Celsius (default 'C')
- `fetchImpl` (function, optional): Custom fetch implementation (for testing/mocks)
- **Returns:** Promise resolving to the current weather object (see OpenWeatherMap docs)
### get24hForecast(lat, lon, options?)
Fetches the next 24 hours of forecast data (3-hour intervals, up to 8 items).
- Same parameters as `getCurrent`
- **Returns:** Promise resolving to an array of forecast objects
### getSun(lat, lon, options?)
Fetches sunrise and sunset times for the given coordinates, returning both UTC and local times.
- Same parameters as `getCurrent`
- **Returns:** Promise resolving to:
```js
{
sunriseUtc: number, // Sunrise time (UTC, Unix timestamp)
sunsetUtc: number, // Sunset time (UTC, Unix timestamp)
sunriseLocal: number, // Sunrise time (local, Unix timestamp)
sunsetLocal: number, // Sunset time (local, Unix timestamp)
offset: number // Timezone offset in seconds (from UTC)
}
```
## TypeScript
Type definitions are included and will be picked up automatically. Example:
```ts
import { getCurrent, get24hForecast, getSun } from '@purinton/openweathermap';
const weather = await getCurrent(40.7128, -74.0060, { apiKey: 'your_api_key_here' });
// weather: object (see OpenWeatherMap API docs)
```
## Support
For help, questions, or to chat with the author and community, visit:
[](https://discord.gg/QSBxQnX7PF)[](https://discord.gg/QSBxQnX7PF)
**[Purinton Dev on Discord](https://discord.gg/QSBxQnX7PF)**
## License
[MIT © 2025 Russell Purinton](LICENSE)
## Links
- [GitHub](https://github.com/purinton/openweathermap)
- [npm](https://www.npmjs.com/package/@purinton/openweathermap)
- [Discord](https://discord.gg/QSBxQnX7PF)