https://github.com/georgianstan/js-climacell-api
JavaScript wrapper for ClimaCell API for both Node and Web env
https://github.com/georgianstan/js-climacell-api
Last synced: 3 months ago
JSON representation
JavaScript wrapper for ClimaCell API for both Node and Web env
- Host: GitHub
- URL: https://github.com/georgianstan/js-climacell-api
- Owner: GeorgianStan
- License: mit
- Created: 2021-01-23T15:03:18.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T18:27:41.000Z (over 2 years ago)
- Last Synced: 2025-02-02T00:35:02.036Z (4 months ago)
- Language: TypeScript
- Size: 565 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# js-climacell-api
`js-climacell-api` is a JavaScript wrapper around the [ClimaCell API](https://docs.climacell.co/reference/api-overview) (v4)
that can be used in both NodeJS and Browser environments
## Installation
_This package is Typescript ready_
```bash
npm i js-climacell-api
```
## How to use it
The library is a default export.
### Browser
To use it browser, you need to use the code from `browser.js` file.
```html
```
or via CDN
```html
```
Where `X.Y.Z` represents the library version.
In this scenario, the library will be bound to the global window object with the property ClimaCellAPI.
`window.ClimaCellAPI` or simple `ClimaCellAPI` can be used to access the library.
If you have a toolchain available you can use an `import` statement.
```ts
import ClimaCellAPI from 'js-climacell-api/browser';
```
```js
const ClimaCellWrapper = require('js-climacell-api/browser');
```
_Because is a default export, here you can import it with what name you want_
---
### Node
For `NodeJS` environment, just replace `browser` with `node`
```ts
import ClimaCellAPI from 'js-climacell-api/node';
```
## Methods
The object imported is a class that will expose the following methods:
```ts
static async requestData(options: QueryBuilderOptions):Promise {}
```
Where `options` is an object of form:
```ts
interface QueryBuilderOptions {
[param: string]: string | number | string[] | number[];
}
```
This static method can be used to compute an URL and send a GET request to `https://data.climacell.co/v4/timelines`.
The values from `options` object will be transformed into query parameters.
_Example_
```ts
await ClimaCellAPI.requestData({
apikey: '23',
location: `1.2%2C2.2`,
fields: ['temperature', 'humidity'],
});
```
will result in a request to the following URL:
```
https://data.climacell.co/v4/timelines?apikey=23&location=1.2%2C2.2&fields=temperature&fields=humidity
```
The result will be exactly the **raw** response from the API.
The purpose of this method is to give you full controll over the request URL and help you easily compute it and acquire [timeline data](https://docs.climacell.co/reference/retrieve-timelines-basic) from the API.
**Don't forget to add your `apikey`!**
---
**For the following methods the class must be instantiated with the following constructor.**
```ts
constructor(apiKey: string, coordinates: GeoCoordinates) {}
```
Where `coordinates` has the following format:
```ts
export type GeoCoordinates = [string | number, string | number]; //latitude & longitude
```
**Example**
```ts
import ClimaCellApi from 'js-climacell-api/dist/node';
const API_KEY = '';
const LAT = '';
const LON = '';
const hometownMonitor = new ClimaCellApi(API_KEY, [LAT, LON]);
```
The available methods are the following:
```ts
async current(options: TimelinesOptions): Promise {}
async perMinute(options: TimelinesOptions): Promise {}
async per5Minutes(options: TimelinesOptions): Promise {}
async per15Minutes(options: TimelinesOptions): Promise {}
async per30Minutes(options: TimelinesOptions): Promise {}
async perDay(options: TimelinesOptions): Promise {}
```
Each method will return the **raw** response from the API.
The types:
```ts
export enum UnitType {
metric = 'metric', // International System of Units
imperial = 'imperial', // Imperial and US customary measurement systems
}
export interface Availability {
start?: string | number;
end?: string | number;
}
export interface TimelinesOptions {
fields: string[];
availability?: Availability;
units?: UnitType;
timezone?: string;
}
```
`availability?: Availability` matches the availability mentioned in the [documentation ](https://docs.climacell.co/reference/data-layers-overview#timestep-availability) and represents the interval of the data requested
`timezone?: string` - Timezone names follow the [IANA Time Zone Database format](https://docs.climacell.co/reference/api-formats#timezone)
`fields` represents an array with the fields you are intersted in ([Core-Air Quality-Pollen-Fire-Precipitation](https://docs.climacell.co/reference/data-layers-overview))
## Examples
```js
(async () => {
const hometownMonitor = new ClimaCellAPI('api_key', [45.6427, 25.5887]);
await hometownMonitor.perMinute({
fields: ['temperature', 'particulateMatter25'],
units: 'imperial',
});
})();
```
Will result in a request to the following URL.
```
https://data.climacell.co/v4/timelines?timesteps=1m&fields=temperature&fields=particulateMatter25&units=imperial&apikey=api_key&location=45.6427,25.5887
```
---
**availability**
```js
await hometownMonitor.perMinute({
fields: ['humidity'],
availability: {
start: '-1h',
end: '2h',
},
});
```
The above call will request data with a time interval of 1m, but starting with 1 hour behind the current time and up to 2 hours in front.
The accepted values for `availability.start` and `availability.end` are
the time formats accepted by [ms](https://www.npmjs.com/package/ms) module.
The next call will request data starting 5 minutes in the future from the current time.
```js
await hometownMonitor.perMinute({
fields: ['humidity'],
availability: {
start: 1000 * 60 * 5,
},
});
```
If you want to use an exact date, then you can implement it as in the following example:
```ts
const specificDate = '2021-01-30T12:07:01.939Z';
await hometownMonitor.perMinute({
fields: ['humidity'],
availability: {
start: new Date(specificDate).getTime() - Date.now(),
},
});
```