@paxperscientiam/national-weather-service-api.ts
v0.3.1
Published
Provides types for the US National Weather Service's forecast API and a helpful URI builder.
Downloads
16
Readme
Provides types for the US National Weather Service's forecast API and a helpful URI builder.
0.3.1
- Fixed missing dependency on npm module "url"
(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