Narcoleptic Possum Mob

    TypeScript icon, indicating that this package has built-in type declarations

    0.8.10 • Public • Published

    npm (scoped) dependencies Status Maintainability Test Coverage


    A library to fetch air quality data from various providers (AQICN, OpenAQ...) and normalizing data into one common format: the openaq-data-format.

    Supported Air Quality Providers

    Provider Provider Code Website Notes
    AQICN aqicn API token needed, get one for free here
    WAQI waqi Same institution as AqiCN
    OpenAQ v2 openaq

    We plan to support more air quality providers in the future see issue #29.

    Get Started

    Install the package:

    yarn install @shootismoke/dataproviders

    The package exposes a couple of data providers (see list above), and for each data provider, there are two main functions:

    • fetchByGps({ latitude, longitude }, options?) - Fetch air quality data by GPS coordinates.
    • fetchByStation(stationId, options?) - Fetch air quality data by station ID.
    // Retrieve the providers by provider code.
    import { aqicn, openaq } from '@shootismoke/dataproviders';
    async function main() {
    	// Fetch the station 1045 on AQICN.
    	const data = await aqicn.fetchByStation(1045);
    	console.log(data.dominentpol); // `dominentpol` is a field specific to AQICN. This logs "pm25".
    	const results = aqicn.normalizeByStation(data); // `results` is an array of normalized OpenAQResults.
    	const res = results[0];
    	console.log(`${res.parameter}: ${res.value} ${res.unit}`); // Logs "pm25: 34.5 µg/m³".
    	// Note how `data.dominentpol` has been converted to `res.parameter`: this is
    	// what we call "normalization" in @shootismoke/providers.

    Usage with fp-ts

    The codebase uses io-ts under the hood to perform runtime data validation, the results are functional programming datatypes (Either<E,A>, Task<E,A>...). If you are already using io-ts and fp-ts]( in your project, it's recommended to import from the /lib/fp subfolder directly.

    // Retrieve the providers by provider code, using fp-ts.
    import { aqicn, openaq } from '@shootismoke/dataproviders/lib/fp';
    aqicn.fetchByGps({ latitude: 45, longitude: 23 }); // Returns a TaskEither<Error, AqicnData>

    Here's a real-world example:

    import { pipe } from 'fp-ts/lib/pipeable';
    import * as TE from 'fp-ts/lib/TaskEither';
    	// Fetch data from station 'Coyhaique' on the OpenAQ platform.
    	// Normalize the data.
    	TE.chain((response) => TE.fromEither(normalize(response))),
    	// Depending on error/result case, do different stuff
    		// Do on error:
    		(error) => {
    			// -- snip --
    		// Do on success:
    		(results) => {
    			const res = results[0]; // `results` is an array of normalized OpenAQ objects
    			console.log(`${res.value} ${res.unit}`); // Logs "34.5 µg/m³"
    			// -- snip --

    Normalized Data Format

    If you use the .normalizeByGps or .normalizeByStation functions, the output will be normalized, i.e. in the same format no matter which provider you use. We follow the openaq-data-format, below are some of its most frequently used fields:

     * The OpenAQ data format. One such object represents one air quality
     * measurement
    interface OpenAQResult {
    	 * City (or regional approximation) containing location
    	city?: string;
    	 * Coordinates where the measurement took place. Note that in the
    	 * openaq-data-format, this field is optional. Using this library, this field
    	 * will **always** be populated
    	coordinates?: {
    		latitude: number;
    		longitude: number;
    	 * Country containing location in two letter ISO format
    	country: string;
    	 * Time of measurement including both local time and UTC time.
    	date: {
    		local: string;
    		utc: string;
    	 * A unique ID representing the location of a measurement (can be a station
    	 * ID, a place...)
    	location: string;
    	 * The pollutant id (pm25, pm10, o3...)
    	parameter: Pollutant;
    	 * The value of the measurement
    	value: number;
    	 * The unit the value is measured in (µg/m³, ppm)
    	unit: Unit;
    	// -- snip --
    	// There are some other optional fields, see docs for more details.
     * The normalized data is an array of OpenAQ results. We ensure there is
     * always at least one element in the Normalized array.
    type OpenAQResults = OpenAQResult[];

    See openaq-data-format for more information.

    Full Documentation

    See the API reference documentation.

    🙋 Contribute

    1. Fork the repo
    2. Make your changes in your own fork
    3. Make sure yarn lint and yarn test pass
    4. Create a Pull Request on this repo


    Look out for *.spec.ts in the codebase. Run:

    yarn test

    📰 License

    GPL-3.0. See LICENSE file for more information.




    npm i @shootismoke/dataproviders

    DownloadsWeekly Downloads






    Unpacked Size

    164 kB

    Total Files


    Last publish


    • amaurym