DarkSky API Wrapper
A wrapper for DarkSky API written in TypeScript.
Usable in node and the browser. If used in a TypeScript project, you will get types, and auto-complete for all of the api responses. You will no longer need to tab back and fourth to the API documentation. Will work in Node or the browser!
This library makes interacting with the DarkSky API a little bit more friendly. It offers promises, request customization, and best of all response types.
If there are any features you would like, please feel free to open up an issue.
Note
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.
Warning
DarkSky explicitly forbids CORS so using darkskyapi-ts
in the browser will not work, and you should instead setup a proxy server and run it on the background.
To prevent API key abuse, you should set up a proxy server to make calls to our API behind the scenes. Then you can provide forecasts to your clients without exposing your API key.
Installation
Add using yarn or npm
yarn add darkskyapi-ts
Usage
Create an account on DarkSky.net, then get your API token.
There are a couple ways to use this library.
TimeMachine request
Any request can be made into a TimeMachine request by passing { time: 'some-timestamp' }
into any function that accepts an optional params
object.
The time
property an be any of the following:
- Date object.
- A valid formatted date-string.
- UNIX timestamp.
Either be a UNIX timestamp or a string formatted as follows:
// UNIX timestamp // Date string// [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS][timezone].
The 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.
Timezone should either be omitted (to refer to local time for the location being requested),
Z
(referring to GMT time), or +[HH][mm] or -[HH][mm] for an offset from GMT in hours and minutes.
1. DarkSky class
Get instance of the factory. See demo/demo_class.ts`
Use any of the DarkSky helper functions (see below).
// Optional Default options // Create the api wrapper class // Use the wrapper /** * Will get the weekly forecast using a helper function, it excludes all of the datablocks except * for the `daily` one. If you need more than that you can use `DarkSky.forecast` and pass in * an Exclude array. */ ;
2. Chaining
You can build a request by using method chaining and a builder pattern.
// Using helper function createRequestChain'api-key', 42, 24 .extendHourly .onlyHourly .excludeFlags .excludeAlerts .execute .thenconsole.log .catchconsole.log // Using the DarkSky classnew DarkSky'api-key' .chain42, 24 .time'May 05 2019' // Library will try it's best to parse this date string .unitsUnits.UK .execute .thenconsole.log .catchconsole.log
3. Manual DarkSky client
This library also exports a minimal DarkSky wrapper, where you can manually create the requests.
createClient'api-key' .timeMachine, .thenconsole.log .catchconsole.log
DarkSky class helper methods
Optional settings when creating a new wrapper:
All helper methods require the location latitude: number, longitude: number
, and can take an optional settings object.
If you need the forecast for a specific date and time, you can use DarkSky's TimeMachine functionality by passing a time
property to each helper function, example:
new DarkSky'api-key'.week42, 24,
Name | Optional | Returns |
---|---|---|
chain() |
RequestParams |
DarkSkyRequestChain |
forecast() |
RequestParams |
Forecast |
timeMachine() |
RequestParams |
Forecast |
current() |
RequestParams |
CurrentForecast |
week() |
RequestParams |
WeekForecast |
day() |
RequestParams |
DayForecast |
hour() |
RequestParams |
HourForecast |
chain()
is a special function that allows you to create a DarkSkyRequestChain
to build your own request, see the example above.
Demo
Demos are available in the demo/
folder. You will NEED a DarkSky API key for the demos to work. Then you can either set it in your env, or pass it as an CLI argument. See the example below.
Note: I recommend VSCode for viewing and editing the examples. It will give you great intellisense about the library.
Follow the steps below:
# Get a API token from DarkSky.net # Either set it in your env export DARKSKY_KEY=your-token # or pass it as a cli argument # npx ts-node --project ../tsconfig.base.json demo_[demo name].ts --key your-key # Build the library yarn && yarn build # Change into demo folder and install dependencies cd demoyarn # Typescript example: npx ts-node --project ../tsconfig.base.json demo_[demo name].ts # To view Browser example, first build project yarn build # Then open `index.html` in your browser
Contributing
See CONTRIBUTING.
License
MIT License Copyright (c) 2019 WorldTurtleMedia Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.