{"id":27200717,"url":"https://github.com/worldturtlemedia/openweathermap-onecall","last_synced_at":"2025-07-06T17:03:14.331Z","repository":{"id":37051880,"uuid":"289117985","full_name":"worldturtlemedia/openweathermap-onecall","owner":"worldturtlemedia","description":"API Wrapper for OpenWeatherMap OneCall written in TypeScript. ","archived":false,"fork":false,"pushed_at":"2025-05-26T16:27:23.000Z","size":1056,"stargazers_count":2,"open_issues_count":20,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-26T17:45:05.178Z","etag":null,"topics":["api-wrapper","darksky-api","openweathermap","openweathermap-onecall","typescript"],"latest_commit_sha":null,"homepage":"https://worldturtlemedia.github.io/openweathermap-onecall/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/worldturtlemedia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-08-20T21:52:40.000Z","updated_at":"2023-02-28T18:13:07.000Z","dependencies_parsed_at":"2023-02-13T19:47:43.382Z","dependency_job_id":"ad092d12-47af-46ee-b27a-480da9a4d07d","html_url":"https://github.com/worldturtlemedia/openweathermap-onecall","commit_stats":{"total_commits":229,"total_committers":7,"mean_commits":"32.714285714285715","dds":0.4672489082969432,"last_synced_commit":"293d3ebdcf81f571dbd6295cc2675c1aa0095e1c"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/worldturtlemedia/openweathermap-onecall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/worldturtlemedia%2Fopenweathermap-onecall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/worldturtlemedia%2Fopenweathermap-onecall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/worldturtlemedia%2Fopenweathermap-onecall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/worldturtlemedia%2Fopenweathermap-onecall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/worldturtlemedia","download_url":"https://codeload.github.com/worldturtlemedia/openweathermap-onecall/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/worldturtlemedia%2Fopenweathermap-onecall/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259400216,"owners_count":22851768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","darksky-api","openweathermap","openweathermap-onecall","typescript"],"created_at":"2025-04-09T21:30:03.818Z","updated_at":"2025-06-12T04:39:53.738Z","avatar_url":"https://github.com/worldturtlemedia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenWeatherMap One Call\n\nA Nodejs and Browser client for the new [OpenWeatherMap \"One Call\" API](https://openweathermap.org/api/one-call-api), written in TypeScript.\n\n![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/worldturtlemedia/openweathermap-onecall/main.yml?branch=master) ![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/worldturtlemedia/openweathermap-onecall/main.yml?branch=next) [![codecov](https://codecov.io/gh/worldturtlemedia/openweathermap-onecall/branch/master/graph/badge.svg?token=GSXRH8UDT3)](https://codecov.io/gh/worldturtlemedia/openweathermap-onecall)\n\n[![npm version](https://badge.fury.io/js/owm-onecall-api.svg)](https://badge.fury.io/js/owm-onecall-api) ![GitHub](https://img.shields.io/github/license/worldturtlemedia/openweathermap-onecall.svg) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/owm-onecall-api.svg)\n\n![GitHub commits since latest release (by SemVer)](https://img.shields.io/github/commits-since/worldturtlemedia/openweathermap-onecall/latest/master?sort=semver)\n\nAn API wrapper for OWM One Call API, usable in node and the browser. It pairs best when used in a TypeScript project, as you will get all the types from the API response. This library makes interacting with the OpenWeatherMap \"One Call\" API a little bit more friendly. It offers promises, request customization, and best of all response types.\n\nIf there are any features you would like, please feel free to open up an issue.\n\n## Motivation\n\nI am also the author of [DarkSky API Client](https://github.com/worldturtlemedia/darksky-api), and I was saddened when I heard that [DarkSky API](https://blog.darksky.net/) annouced it was being shut down after being acquired from Apple.\n\nThere was not really an similar \"one-call\" experience, so it looks like [OpenWeatherMap](https://openweathermap.org/api/one-call-3) saw an opportunity and took it. For right now this library will **only** support the \"one-call\" API. There are plenty other libraries on NPM that cover the rest of the APIs.\n\n**Again**: This will _only_ support the one-call API (for now).\n\n### Notes\n\n- I did my best to correctly add types for all of the supported endpoints. However if you notice an incorrect payload type, or some missing properties, please open up an issue, or submit a pull request.\n- For use in the browser, you will need a CORS proxy.\n\n## Features\n\n- This library is powered by [tsdx](https://tsdx.io/), and outputs ~~UMD~~, CommonJS, and an ESM bundle.\n- Supports OpenWeatherMap's new \"one-call\" API\n  - Similar to what DarkSky's API was.\n- Tree-shakeable! Keep those bundles small.\n- Tested\n- Generated library documentation\n- Easy integration into an existing codebase that uses [DarkSky](https://github.com/worldturtlemedia/openweathermap-onecall/blob/master/DARKSKY.md).\n\n## TODO\n\n- Add ability to pass in a CORS anywhere proxy\n\n## Installation\n\n```bash\nyarn add owm-onecall-api\n\n# or\n\nnpm install owm-onecall-api\n```\n\n## Getting started\n\nYou will need to obtain a API token from [OpenWeatherMap](https://openweathermap.org/price).\n\nThe free tier does give you access to the \"one-call\" endpoint. A subscription is now required when using the OneCall API. If you receive a 401 when getting the forecast that is the reason. You must subscibe to their new pricing model.\n\n## Usage\n\nCreate an account on [OpenWeatherMap](https://openweathermap.org/api/one-call-3), then get your API token.\n\nThere are a couple ways to use this library.\n\n### DarkSky Compatibility\n\nFor integrating this library with an existing codebase that used to use DarkSky, please see the [DarkSky - Compat](https://github.com/worldturtlemedia/openweathermap-onecall/blob/master/DARKSKY.md) document.\n\n### TimeMachine request\n\nAny request can be made into a TimeMachine request by passing `{ time: 'some-timestamp' }` into any function that accepts an optional `params` object.\n\nThe `time` property an be any of the following:\n\n- Date object.\n- A valid formatted date-string.\n- UNIX timestamp.\n\nEither be a UNIX timestamp or a string formatted as follows:\n\n```typescript\n// UNIX timestamp\n{\n  time: 1558575452\n}\n\n// Date string\n// [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS][timezone].\n{\n  time: \"2019-01-01T00:00:00+0400\"\n}\n```\n\nThe library will try it's best to parse the Date string you pass in, so you don't _need_ to supply it in the above format. But for safety its probably best.\n\n\u003e Timezone should either be omitted (to refer to local time for the location being requested),\n\u003e `Z` (referring to GMT time), or +[HH][mm] or -[HH][mm] for an offset from GMT\n\u003e in hours and minutes.\n\n## 1. OpenWeatherMapClient class\n\nGet instance of the factory.\n\nUse any of the OpenWeatherMapClient helper functions (see below).\n\n```typescript\n// Optional Default options\nconst options: OpenWeatherMapOptions = {\n  // Optional\n  // Anything set here can be overriden when making the request\n\n  units: Units.Metric,\n  lang: Language.FRENCH,\n}\n\n// Create the api wrapper class\nconst openWeatherMap = new OpenWeatherMap(KEY, options)\n\n// Use the wrapper\n\n/**\n * Will get the weekly forecast using a helper function, it excludes all of the datablocks except\n * for the `daily` one.  If you need more than that you can use `DarkSky.forecast` and pass in\n * an Exclude array.\n */\nasync function getWeeklyForecast(\n  lat: number,\n  lon: number\n): Promise\u003cWeekForecast\u003e {\n  try {\n    // You can pass options here to override the options set above\n    const result: WeekForecast = await openWeatherMap.week(lat, lon, {\n      lang: Language.ENGLISH,\n    })\n    console.log(`Got forecast for ${result.lat}-${result.lon}`)\n    return result\n  } catch (error) {\n    // If OpenWeatherMap API doesn't return a 'daily' data-block, then this function will throw\n    console.log(\"Unable to get the weekly forecast for the chosen location\")\n  }\n}\n\n;(async () =\u003e {\n  const forecast = await getWeeklyForecast(42, 24)\n\n  console.log(`Forecast for tomorrow: ${forecast.daily.temp.max}`)\n})()\n```\n\n## 2. Chaining\n\nYou can build a request by using method chaining and a builder pattern.\n\n```typescript\n// Using helper function\nimport { buildOpenWeatherMapRequest } from \"owm-onecall-api\"\n\nbuildOpenWeatherMapRequest(\"api-key\", 42, 24)\n  .extendHourly()\n  .onlyHourly()\n  .execute()\n  .then(console.log)\n  .catch(console.log)\n\n// Using the DarkSky class\nnew OpenWeatherMap(\"api-key\")\n  .builder(42, 24)\n  .time(\"May 05 2019\") // Library will try it's best to parse this date string\n  .units(Units.UK)\n  .execute()\n  .then(console.log)\n  .catch(console.log)\n```\n\n## 3. Manual OpenWeatherMap client\n\nThis library also exports a minimal OpenWeatherMap wrapper, where you can manually create the requests.\n\n```typescript\nimport { openWeatherMapClient } from \"owm-onecall-api\"\n\nconst targetDate = new Date(1558000000 * 1000)\n\nopenWeatherMapClient(\"api-key\")\n  .timeMachine({ lat: 42, lon: 24, time: targetDate }, { units: Units.Metric })\n  .then(console.log)\n  .catch(console.log)\n```\n\n## OpenWeatherMap class helper methods\n\nOptional settings when creating a new wrapper:\n\n```typescript\nexport interface OpenWeatherMapOptions {\n  /**\n   * Return weather conditions in the requested units.\n   */\n  units?: Units\n\n  /**\n   * Return summary properties in the desired language.\n   *\n   * @default Language.ENGLISH\n   */\n  lang?: Language\n\n  /**\n   * Exclude some number of data blocks from the API response.\n   */\n  exclude?: Exclude[]\n\n  /**\n   * Optional config to change the way axios makes the request.\n   */\n  requestConfig?: AxiosRequestConfig\n}\n```\n\nAll helper methods require the location `lat: number, lon: number`, and can take an optional settings object.\n\nIf you need the forecast for a specific date and time, you can use OpenWeathMaps's TimeMachine functionality by passing a `time` property to each helper function, example:\n\n```typescript\nnew OpenWeatherMap(\"api-key\").week(42, 24, { time: \"May 5 2018\" })\n```\n\n## Demo\n\nA demo is available in the `demo/` folder, in order to run follow these steps:\n\n1. Get an API key from OWM\n1. Make sure you are subscribed to their pricing plan\n1. Run the following commands:\n\n```sh\nyarn build\nnode demo --key \u003cINSERT API KEY\u003e\n```\n\nYou can change the default latitude and longitude by passing `--lat` and `--lon`.\n\n## License\n\n```text\nMIT License\n\nCopyright (c) 2023 Jordon de Hoog\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworldturtlemedia%2Fopenweathermap-onecall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworldturtlemedia%2Fopenweathermap-onecall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworldturtlemedia%2Fopenweathermap-onecall/lists"}