@paxperscientiam/national-weather-service-api.ts

Provides types for the US National Weather Service's forecast API and a helpful URI builder.

(Breaking) changes starting with version 0.3.0

• methods no longer end with suffix "Service"
• query types are shorter and hence easier to read. For the time being, they have differing hash substrings. This at least gives query types a fixed length.
• the exposed class is now simply called "NWS."

Relevant websites:

• https://www.weather.gov/documentation/services-web-api
• https://forecast-v3.weather.gov/documentation
• https://api.weather.gov/openapi.json
• https://github.com/weather-gov/api/blob/master/general-faqs.md

And, the endpoint:

• https://api.weather.gov/

Motivation

TypeScript makes building API requests more straightforward.

Installation

pnpm install @paxperscientiam/national-weather-service-api.ts

or ...

npm install @paxperscientiam/national-weather-service-api.ts

or ...

yarn add @paxperscientiam/national-weather-service-api.ts

Importing

import {
    NWS
} from "@paxperscientiam/national-weather-service-api.ts"

const {
    NWS
} = require("@paxperscientiam/national-weather-service-api.ts")

Under the hood

For example, say you want to make a request to the "Alerts" endpoint of the NWS forecast API (I.E. https://api.weather.gov/alerts). This endpoint accepts URL queries.

Here's the interface for those parameters:

declare namespace NWSDataAPI {
    namespace Alerts {
        export interface IQuery {
            active?: Parameters.IActive;
            start?: Parameters.IStart; // date-time
            end?: Parameters.IEnd; // date-time
            status?: Parameters.IStatus;
            message_type?: Parameters.IMessageType;
            event?: Parameters.IEvent;
            code?: Parameters.ICode;
            region_type?: Parameters.IRegionType;
            point?: Parameters.IPoint; // ^(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)$
            region?: Parameters.IRegion;
            area?: Parameters.IArea;
            zone?: Parameters.IZone;
            urgency?: Parameters.IUrgency;
            severity?: Parameters.ISeverity;
            certainty?: Parameters.ICertainty;
            limit?: Parameters.ILimit;
            cursor?: Parameters.ICursor;
        }
        namespace Parameters {
            export type IActive = boolean;
            export type IArea = ("AL" | "AK" | "AS" | "AR" | "AZ" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "GU" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "OH" | "OK" | "OR" | "PA" | "PR" | "RI" | "SC" | "SD" | "TN" | "TX" | "UT" | "VT" | "VI" | "VA" | "WA" | "WV" | "WI" | "WY" | "PZ" | "PK" | "PH" | "PS" | "PM" | "AN" | "AM" | "GM" | "LS" | "LM" | "LH" | "LC" | "LE" | "LO")[];
            export type ICertainty = ("unknown" | "unlikely" | "possible" | "likely" | "observed")[];
            export type ICode = string /* ^\w{3}$ */ [];
            export type ICursor = string;
            export type IEnd = string; // date-time
            export type IEvent = string /* ^[A-Za-z0-9 ]+$ */ [];
            export type ILimit = number;
            export type IMessageType = ("alert" | "update" | "cancel")[];
            export type IPoint = string; // ^(-?\d+(?:\.\d+)?),(-?\d+(?:\.\d+)?)$
            export type IRegion = ("AL" | "AT" | "GL" | "GM" | "PA" | "PI")[];
            export type IRegionType = "land" | "marine";
            export type ISeverity = ("unknown" | "minor" | "moderate" | "severe" | "extreme")[];
            export type IStart = string; // date-time
            export type IStatus = ("actual" | "exercise" | "system" | "test" | "draft")[];
            export type IUrgency = ("unknown" | "past" | "future" | "expected" | "immediate")[];
            export type IZone = string /* ^\w{2}[CZ]\d{3}$ */ [];
        }
        namespace Responses {
            export type IDefault = Components.Responses.IError;
        }
    }

The exposed class is NWS. The method corresponding to the https://api.weather.gov/alerts endpoint looks like this:

export class NWS {
    private domain: string = "https://api.weather.gov"
    private query: any
    private pathString: string = ""

    constructor() {
        return this
    }
    // Returns all alerts
    AlertsService(query?: NWSDataAPI.Alerts.IQuery) {
        if (query) {
            this.query = query
        }
        this.pathString = `/alerts`
        return this
    }

Example

With all this said, here's how you might use this:

import { NWS } from "@paxperscientiam/national-weather-service-api.ts"

const nws = new NWS()

const alerts = nws.AlertsService({
    active: true,
})

const url = alerts.buildURI()
// => "https://api.weather.gov/alerts?active=true"

To-do

• simplify query Types
• improve generation code

Humans

• https://github.com/horiuchi/dtsgenerator
• US National Weather Service
• Fine folks at freenode/##javascript