OpenWeather API Node.js Client

Common errors

• TypeError: OpenWeatherAPI is not a constructor

  cause Attempting to instantiate the OpenWeatherAPI class incorrectly, often due to a mismatch between module import syntax (ESM vs. CommonJS) and the actual export.
  fix For ESM/TypeScript, use `import OpenWeatherAPI from 'openweather-api-node'; new OpenWeatherAPI(...)`. For CommonJS, use `const { OpenWeatherAPI } = require('openweather-api-node'); new OpenWeatherAPI(...)`.

• Error: No API key provided.

  cause The OpenWeatherAPI instance was initialized without a valid API key.
  fix Ensure the `key` property is set in the constructor options, e.g., `new OpenWeatherAPI({ key: 'YOUR_API_KEY', ... })`, or by using `weather.setKey('YOUR_API_KEY')`.

• TS2305: Module '"openweather-api-node"' has no default export.

  cause A TypeScript project (likely configured for CommonJS module resolution or using an older compiler target) is attempting a default import where a named import is expected for CJS, or vice-versa with module interop settings.
  fix If targeting ESM, ensure `tsconfig.json` has `"module": "ESNext"` or similar. If targeting CommonJS, use `import * as OpenWeatherAPI from 'openweather-api-node'` and then `new OpenWeatherAPI.OpenWeatherAPI(...)` or adjust `allowSyntheticDefaultImports` in `tsconfig.json`.

• Property 'weather' does not exist on type 'WeatherData' | 'OneCallData'.

  cause This error can occur if the API response structure has changed, particularly after updating to v2.0.0 (camelCase changes) or v3.0.0 (getHistory return type), or if you are incorrectly accessing nested properties.
  fix Consult the current documentation for the exact response structure of the method you are calling. Ensure property names are `camelCase` and adjust nested accessors if the object shape has changed.

Warnings

• breaking Starting with v3.1.0, the `axios` dependency was removed. If your application relied on `axios` being a transitive dependency or expected `axios`-specific error structures, you might need to adjust your error handling or explicitly install `axios` if still needed elsewhere.
  Fix: Review any code that might have indirectly relied on `axios` or its specific response/error formats. The library now uses native `fetch` or a lightweight alternative.
• breaking Version 3.0.0 introduced support for the new OneCall API 3.0, and the return type of the `getHistory` method was changed. If you were using the older OneCall API, you might encounter breaking changes.
  Fix: For the old OneCall API, downgrade to `openweather-api-node@2.1.2`. Review the documentation for v3.x's `getHistory` method for updated return types and adapt your code accordingly.
• breaking Version 2.0.0 was a complete rewrite in TypeScript. Variable styles in Weather Objects changed to `camelCase`, and the `mergeWeathers` method was removed. Existing code relying on older snake_case properties or the removed method will break.
  Fix: Update all property access to use `camelCase` (e.g., `temp_cur` becomes `temp.cur`). Refactor any logic that used `mergeWeathers`.
• gotcha The import style for the `OpenWeatherAPI` class differs between ESM (TypeScript/modern Node.js) and CommonJS environments. Incorrectly importing can lead to `TypeError: OpenWeatherAPI is not a constructor` or `TS2305: Module ... has no default export`.
  Fix: For ESM/TypeScript, use `import OpenWeatherAPI from 'openweather-api-node'`. For CommonJS, use `const { OpenWeatherAPI } = require('openweather-api-node')`.
• gotcha An API key from OpenWeatherMap is absolutely required for nearly all operations. Without a valid key, API requests will fail with authorization errors.
  Fix: Ensure you have obtained an API key from OpenWeatherMap and pass it correctly during initialization via the `key` option or `setKey` method. Always protect your API keys.

Install

• npm install openweather-api-node npm
• yarn add openweather-api-node yarn
• pnpm add openweather-api-node pnpm

Imports

• OpenWeatherAPI
  wrong:

  import { OpenWeatherAPI } from 'openweather-api-node'

  correct:

  import OpenWeatherAPI from 'openweather-api-node'

  For ESM projects (e.g., TypeScript or modern Node.js modules), the main class is a default export.
• OpenWeatherAPI
  wrong:

  const OpenWeatherAPI = require('openweather-api-node')

  correct:

  const { OpenWeatherAPI } = require('openweather-api-node')

  For CommonJS projects, the main class is exported as a named property of the module object.
• OpenWeatherAPI_Options
  wrong:

  import { OpenWeatherAPI_Options } from 'openweather-api-node'

  correct:

  import type { OpenWeatherAPI_Options } from 'openweather-api-node'

  Import only the type definition for configuration options, available since v1.3.0.

Quickstart

Demonstrates initializing the OpenWeatherAPI client with an API key and location, then fetching current weather and forecast data.

import OpenWeatherAPI from "openweather-api-node";

const weather = new OpenWeatherAPI({
    key: process.env.OPENWEATHER_API_KEY ?? '', // Ensure your API key is set as an environment variable
    locationName: "New York",
    units: "imperial"
});

weather.getCurrent().then(data => {
    console.log(`Current temperature in New York is: ${data.weather.temp.cur}\u00B0F`);
}).catch(error => {
    console.error("Failed to fetch current weather:", error.message);
});

weather.getForecast().then(data => {
    console.log(`Forecast for New York (first entry): ${data.weather[0].temp.day}\u00B0F`);
}).catch(error => {
    console.error("Failed to fetch forecast:", error.message);
});