us-gov-open-data-mcp 1.0.0

package/dist/sdk/usda-fooddata.js

@@ -0,0 +1,80 @@
+/**
+ * USDA FoodData Central SDK — typed API client for the FDC API.
+ *
+ * Standalone — no MCP server required. Usage:
+ *
+ *   import { searchFoods, getFood, listFoods } from "us-gov-open-data/sdk/usda-fooddata";
+ *
+ *   const results = await searchFoods({ query: "cheddar cheese", pageSize: 5 });
+ *   console.log(results.foods);
+ *
+ *   const food = await getFood(167782);
+ *   console.log(food.description, food.foodNutrients);
+ *
+ * Requires DATA_GOV_API_KEY env var. Get one at https://api.data.gov/signup/
+ * Docs: https://fdc.nal.usda.gov/api-guide
+ */
+import { createClient } from "../client.js";
+// ─── Client ──────────────────────────────────────────────────────────
+const api = createClient({
+    baseUrl: "https://api.nal.usda.gov/fdc/v1",
+    name: "usda-fooddata",
+    auth: { type: "query", key: "api_key", envVar: "DATA_GOV_API_KEY" },
+    rateLimit: { perSecond: 3, burst: 10 }, // 1000 req/hour
+    cacheTtlMs: 24 * 60 * 60 * 1000, // 24 hours — nutrition data is static
+});
+// ─── Reference Data ──────────────────────────────────────────────────
+export const DATA_TYPES = {
+    Foundation: "Foundation Foods — minimally processed, nutrient-dense foods",
+    "SR Legacy": "Standard Reference Legacy — historical USDA reference data",
+    Survey: "FNDDS — Food and Nutrient Database for Dietary Studies",
+    Branded: "Branded Foods — from food manufacturers (largest dataset)",
+    Experimental: "Experimental Foods — research data",
+};
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Search for foods by keyword.
+ *
+ * Example:
+ *   const results = await searchFoods({ query: "chicken breast", dataType: ["Foundation", "SR Legacy"] });
+ */
+export async function searchFoods(opts) {
+    return api.get("/foods/search", {
+        query: opts.query,
+        dataType: opts.dataType,
+        pageSize: opts.pageSize,
+        pageNumber: opts.pageNumber,
+        sortBy: opts.sortBy,
+        sortOrder: opts.sortOrder,
+        brandOwner: opts.brandOwner,
+    });
+}
+/**
+ * Get detailed food information by FDC ID.
+ *
+ * Example:
+ *   const food = await getFood(167782);
+ */
+export async function getFood(fdcId) {
+    return api.get(`/food/${fdcId}`);
+}
+/**
+ * Get a paged list of foods (abridged format).
+ *
+ * Example:
+ *   const list = await listFoods({ dataType: ["Foundation"], pageSize: 25 });
+ */
+export async function listFoods(opts = {}) {
+    return api.get("/foods/list", {
+        dataType: opts.dataType,
+        pageSize: opts.pageSize,
+        pageNumber: opts.pageNumber,
+        sortBy: opts.sortBy,
+        sortOrder: opts.sortOrder,
+    });
+}
+/** Clear cached responses. */
+export function clearCache() {
+    api.clearCache();
+}
+//# sourceMappingURL=usda-fooddata.js.map

package/dist/sdk/usda-fooddata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usda-fooddata.js","sourceRoot":"","sources":["../../src/sdk/usda-fooddata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,wEAAwE;AAExE,MAAM,GAAG,GAAG,YAAY,CAAC;IACvB,OAAO,EAAE,iCAAiC;IAC1C,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE;IACnE,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,gBAAgB;IACxD,UAAU,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,sCAAsC;CACxE,CAAC,CAAC;AA+DH,wEAAwE;AAExE,MAAM,CAAC,MAAM,UAAU,GAA2B;IAChD,UAAU,EAAE,8DAA8D;IAC1E,WAAW,EAAE,4DAA4D;IACzE,MAAM,EAAE,wDAAwD;IAChE,OAAO,EAAE,2DAA2D;IACpE,YAAY,EAAE,oCAAoC;CACnD,CAAC;AAEF,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAQjC;IACC,OAAO,GAAG,CAAC,GAAG,CAAmB,eAAe,EAAE;QAChD,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAAa;IACzC,OAAO,GAAG,CAAC,GAAG,CAAa,SAAS,KAAK,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAM5B,EAAE;IACJ,OAAO,GAAG,CAAC,GAAG,CAAiB,aAAa,EAAE;QAC5C,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAC;AACL,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,UAAU;IACxB,GAAG,CAAC,UAAU,EAAE,CAAC;AACnB,CAAC"}

package/dist/sdk/usda-nass.d.ts

@@ -0,0 +1,75 @@
+/**
+ * USDA NASS QuickStats SDK — agricultural production, crop prices, farm income.
+ *
+ * API docs: https://quickstats.nass.usda.gov/api
+ * Get key: https://quickstats.nass.usda.gov/api#param_define
+ * Rate limit: not documented, be conservative
+ * Max 50,000 records per request.
+ *
+ * Usage:
+ *   import { queryStats, getTopCommodities } from "us-gov-open-data-mcp/sdk/usda-nass";
+ *   const corn = await queryStats({ commodity_desc: "CORN", year: 2024, state_alpha: "IA" });
+ */
+export interface NassRecord {
+    source_desc: string;
+    sector_desc: string;
+    group_desc: string;
+    commodity_desc: string;
+    class_desc: string;
+    prodn_practice_desc: string;
+    util_practice_desc: string;
+    statisticcat_desc: string;
+    unit_desc: string;
+    short_desc: string;
+    domain_desc: string;
+    domaincat_desc: string;
+    agg_level_desc: string;
+    state_alpha: string;
+    state_name: string;
+    county_name: string;
+    year: number;
+    freq_desc: string;
+    begin_code: string;
+    end_code: string;
+    reference_period_desc: string;
+    Value: string;
+    CV: string;
+}
+export interface NassQueryParams {
+    source_desc?: string;
+    sector_desc?: string;
+    commodity_desc?: string;
+    statisticcat_desc?: string;
+    unit_desc?: string;
+    domain_desc?: string;
+    state_alpha?: string;
+    year?: number | string;
+    freq_desc?: string;
+    agg_level_desc?: string;
+    format?: string;
+}
+/** Get record count for a query (check before fetching — max 50,000). */
+export declare function getCount(params: NassQueryParams): Promise<number>;
+/** Query agricultural statistics. Returns up to 50,000 records. */
+export declare function queryStats(params: NassQueryParams): Promise<NassRecord[]>;
+/** Get valid values for a specific parameter (for discovery). */
+export declare function getParamValues(param: string, opts?: NassQueryParams): Promise<Record<string, string[]>>;
+/** Convenience: get crop production data for a commodity + state + year. */
+export declare function getCropProduction(commodity: string, opts?: {
+    state?: string;
+    year?: number;
+    category?: string;
+}): Promise<NassRecord[]>;
+/** Convenience: get livestock data. */
+export declare function getLivestockData(commodity: string, opts?: {
+    state?: string;
+    year?: number;
+    category?: string;
+}): Promise<NassRecord[]>;
+/** Convenience: get price received by farmers. */
+export declare function getPriceReceived(commodity: string, opts?: {
+    state?: string;
+    year?: number;
+}): Promise<NassRecord[]>;
+export declare function clearCache(): void;
+//# sourceMappingURL=usda-nass.d.ts.map

package/dist/sdk/usda-nass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usda-nass.d.ts","sourceRoot":"","sources":["../../src/sdk/usda-nass.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,yEAAyE;AACzE,wBAAsB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAMvE;AAED,mEAAmE;AACnE,wBAAsB,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAM/E;AAED,iEAAiE;AACjE,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAO7G;AAED,4EAA4E;AAC5E,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClD,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAUxB;AAED,uCAAuC;AACvC,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClD,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAUxB;AAED,kDAAkD;AAClD,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CAC/B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CASxB;AAED,wBAAgB,UAAU,IAAI,IAAI,CAAsB"}

package/dist/sdk/usda-nass.js

@@ -0,0 +1,83 @@
+/**
+ * USDA NASS QuickStats SDK — agricultural production, crop prices, farm income.
+ *
+ * API docs: https://quickstats.nass.usda.gov/api
+ * Get key: https://quickstats.nass.usda.gov/api#param_define
+ * Rate limit: not documented, be conservative
+ * Max 50,000 records per request.
+ *
+ * Usage:
+ *   import { queryStats, getTopCommodities } from "us-gov-open-data-mcp/sdk/usda-nass";
+ *   const corn = await queryStats({ commodity_desc: "CORN", year: 2024, state_alpha: "IA" });
+ */
+import { createClient } from "../client.js";
+const api = createClient({
+    baseUrl: "https://quickstats.nass.usda.gov",
+    name: "usda-nass",
+    auth: { type: "query", key: "key", envVar: "USDA_NASS_API_KEY" },
+    rateLimit: { perSecond: 2, burst: 5 },
+    cacheTtlMs: 12 * 60 * 60 * 1000, // 12 hours — agricultural data updates infrequently
+});
+// ─── Public API ──────────────────────────────────────────────────────
+/** Get record count for a query (check before fetching — max 50,000). */
+export async function getCount(params) {
+    const data = await api.get("/api/get_counts", {
+        ...params,
+        format: "json",
+    });
+    return data.count ?? 0;
+}
+/** Query agricultural statistics. Returns up to 50,000 records. */
+export async function queryStats(params) {
+    const data = await api.get("/api/api_GET/", {
+        ...params,
+        format: "json",
+    });
+    return data.data ?? [];
+}
+/** Get valid values for a specific parameter (for discovery). */
+export async function getParamValues(param, opts) {
+    const data = await api.get(`/api/get_param_values/`, {
+        param,
+        ...opts,
+        format: "json",
+    });
+    return data;
+}
+/** Convenience: get crop production data for a commodity + state + year. */
+export async function getCropProduction(commodity, opts) {
+    return queryStats({
+        source_desc: "SURVEY",
+        sector_desc: "CROPS",
+        commodity_desc: commodity.toUpperCase(),
+        statisticcat_desc: opts?.category ?? "PRODUCTION",
+        state_alpha: opts?.state?.toUpperCase(),
+        year: opts?.year,
+        agg_level_desc: opts?.state ? "STATE" : "NATIONAL",
+    });
+}
+/** Convenience: get livestock data. */
+export async function getLivestockData(commodity, opts) {
+    return queryStats({
+        source_desc: "SURVEY",
+        sector_desc: "ANIMALS & PRODUCTS",
+        commodity_desc: commodity.toUpperCase(),
+        statisticcat_desc: opts?.category,
+        state_alpha: opts?.state?.toUpperCase(),
+        year: opts?.year,
+        agg_level_desc: opts?.state ? "STATE" : "NATIONAL",
+    });
+}
+/** Convenience: get price received by farmers. */
+export async function getPriceReceived(commodity, opts) {
+    return queryStats({
+        source_desc: "SURVEY",
+        commodity_desc: commodity.toUpperCase(),
+        statisticcat_desc: "PRICE RECEIVED",
+        state_alpha: opts?.state?.toUpperCase(),
+        year: opts?.year,
+        freq_desc: "ANNUAL",
+    });
+}
+export function clearCache() { api.clearCache(); }
+//# sourceMappingURL=usda-nass.js.map

package/dist/sdk/usda-nass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usda-nass.js","sourceRoot":"","sources":["../../src/sdk/usda-nass.ts"],"names":[],"mappings":"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"}

package/dist/sdk/usgs.d.ts

@@ -0,0 +1,221 @@
+/**
+ * USGS SDK — typed API client for earthquake data and water services.
+ *
+ * Standalone — no MCP server required. Usage:
+ *
+ *   import { searchEarthquakes, getWaterData } from "us-gov-open-data/sdk/usgs";
+ *
+ *   const quakes = await searchEarthquakes({ minmagnitude: 5, starttime: "2024-01-01" });
+ *   const water = await getWaterData({ sites: "01646500", parameterCd: "00060" });
+ *
+ * No API key required.
+ * Docs:
+ *   Earthquake: https://earthquake.usgs.gov/fdsnws/event/1/
+ *   Water Services: https://waterservices.usgs.gov/
+ */
+export interface EarthquakeFeature {
+    type: "Feature";
+    properties: {
+        mag?: number;
+        place?: string;
+        time?: number;
+        updated?: number;
+        tz?: number;
+        url?: string;
+        detail?: string;
+        felt?: number;
+        cdi?: number;
+        mmi?: number;
+        alert?: string;
+        status?: string;
+        tsunami?: number;
+        sig?: number;
+        net?: string;
+        code?: string;
+        ids?: string;
+        sources?: string;
+        types?: string;
+        nst?: number;
+        dmin?: number;
+        rms?: number;
+        gap?: number;
+        magType?: string;
+        type?: string;
+        title?: string;
+        [key: string]: unknown;
+    };
+    geometry: {
+        type: "Point";
+        coordinates: [number, number, number];
+    };
+    id: string;
+}
+export interface EarthquakeResponse {
+    type: "FeatureCollection";
+    metadata: {
+        generated: number;
+        url: string;
+        title: string;
+        status: number;
+        api: string;
+        count: number;
+    };
+    features: EarthquakeFeature[];
+}
+export interface EarthquakeCount {
+    count: number;
+    maxAllowed: number;
+}
+export interface WaterValue {
+    value: string;
+    qualifiers: string[];
+    dateTime: string;
+}
+export interface WaterTimeSeries {
+    sourceInfo: {
+        siteName?: string;
+        siteCode?: Array<{
+            value: string;
+            network?: string;
+            agencyCode?: string;
+        }>;
+        geoLocation?: {
+            geogLocation?: {
+                latitude: number;
+                longitude: number;
+            };
+        };
+        [key: string]: unknown;
+    };
+    variable: {
+        variableCode?: Array<{
+            value: string;
+            variableID?: number;
+        }>;
+        variableName?: string;
+        unit?: {
+            unitCode?: string;
+        };
+        [key: string]: unknown;
+    };
+    values: Array<{
+        value: WaterValue[];
+        method?: Array<{
+            methodDescription?: string;
+            methodID?: number;
+        }>;
+    }>;
+}
+export interface WaterResponse {
+    name: string;
+    declaredType: string;
+    value: {
+        timeSeries: WaterTimeSeries[];
+        [key: string]: unknown;
+    };
+}
+/** Common USGS water parameter codes. */
+export declare const WATER_PARAMS: Record<string, string>;
+/** Earthquake alert levels. */
+export declare const ALERT_LEVELS: Record<string, string>;
+/**
+ * Search for earthquakes using USGS FDSN Event Web Service.
+ *
+ * Example:
+ *   const quakes = await searchEarthquakes({ minmagnitude: 5, starttime: "2024-01-01" });
+ *   const nearby = await searchEarthquakes({ latitude: 37.77, longitude: -122.42, maxradiuskm: 100 });
+ */
+export declare function searchEarthquakes(opts: {
+    starttime?: string;
+    endtime?: string;
+    minmagnitude?: number;
+    maxmagnitude?: number;
+    mindepth?: number;
+    maxdepth?: number;
+    latitude?: number;
+    longitude?: number;
+    maxradiuskm?: number;
+    minlatitude?: number;
+    maxlatitude?: number;
+    minlongitude?: number;
+    maxlongitude?: number;
+    limit?: number;
+    orderby?: "time" | "time-asc" | "magnitude" | "magnitude-asc";
+    alertlevel?: "green" | "yellow" | "orange" | "red";
+}): Promise<EarthquakeResponse>;
+/**
+ * Count earthquakes matching the given criteria.
+ *
+ * Example:
+ *   const count = await countEarthquakes({ minmagnitude: 4, starttime: "2024-01-01" });
+ */
+export declare function countEarthquakes(opts: {
+    starttime?: string;
+    endtime?: string;
+    minmagnitude?: number;
+    maxmagnitude?: number;
+    latitude?: number;
+    longitude?: number;
+    maxradiuskm?: number;
+}): Promise<EarthquakeCount>;
+/**
+ * Get the latest significant earthquakes (last 30 days, magnitude 4.5+).
+ */
+export declare function getSignificantEarthquakes(): Promise<EarthquakeResponse>;
+/**
+ * Get USGS water data (streamflow, water level, temperature, etc.) from monitoring sites.
+ *
+ * Example:
+ *   const data = await getWaterData({ sites: "01646500", parameterCd: "00060" });
+ *   const data = await getWaterData({ stateCd: "CA", parameterCd: "00060", period: "P7D" });
+ */
+export declare function getWaterData(opts: {
+    sites?: string;
+    stateCd?: string;
+    countyCd?: string;
+    huc?: string;
+    parameterCd?: string;
+    period?: string;
+    startDT?: string;
+    endDT?: string;
+    siteType?: string;
+    siteStatus?: "all" | "active" | "inactive";
+}): Promise<WaterResponse>;
+/**
+ * Search for USGS water monitoring sites.
+ *
+ * Example:
+ *   const sites = await searchWaterSites({ stateCd: "CA", siteType: "ST" });
+ */
+export declare function searchWaterSites(opts: {
+    stateCd?: string;
+    countyCd?: string;
+    huc?: string;
+    siteType?: string;
+    siteStatus?: "all" | "active" | "inactive";
+    hasDataTypeCd?: string;
+}): Promise<unknown>;
+/**
+ * Get USGS daily value water data (historical daily averages).
+ * Unlike instantaneous values (iv), these are aggregated daily means.
+ *
+ * Example:
+ *   const data = await getDailyWaterData({ sites: '01646500', parameterCd: '00060', period: 'P30D' });
+ *   const data = await getDailyWaterData({ stateCd: 'CA', parameterCd: '00065', startDT: '2024-01-01', endDT: '2024-12-31' });
+ */
+export declare function getDailyWaterData(opts: {
+    sites?: string;
+    stateCd?: string;
+    countyCd?: string;
+    huc?: string;
+    parameterCd?: string;
+    period?: string;
+    startDT?: string;
+    endDT?: string;
+    siteType?: string;
+    siteStatus?: "all" | "active" | "inactive";
+    statCd?: string;
+}): Promise<WaterResponse>;
+/** Clear all USGS caches. */
+export declare function clearCache(): void;
+//# sourceMappingURL=usgs.d.ts.map

package/dist/sdk/usgs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usgs.d.ts","sourceRoot":"","sources":["../../src/sdk/usgs.ts"],"names":[],"mappings":"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"}

package/dist/sdk/usgs.js

@@ -0,0 +1,182 @@
+/**
+ * USGS SDK — typed API client for earthquake data and water services.
+ *
+ * Standalone — no MCP server required. Usage:
+ *
+ *   import { searchEarthquakes, getWaterData } from "us-gov-open-data/sdk/usgs";
+ *
+ *   const quakes = await searchEarthquakes({ minmagnitude: 5, starttime: "2024-01-01" });
+ *   const water = await getWaterData({ sites: "01646500", parameterCd: "00060" });
+ *
+ * No API key required.
+ * Docs:
+ *   Earthquake: https://earthquake.usgs.gov/fdsnws/event/1/
+ *   Water Services: https://waterservices.usgs.gov/
+ */
+import { createClient } from "../client.js";
+// ─── Clients ─────────────────────────────────────────────────────────
+const earthquakeApi = createClient({
+    baseUrl: "https://earthquake.usgs.gov",
+    name: "usgs-earthquake",
+    rateLimit: { perSecond: 5, burst: 10 },
+    cacheTtlMs: 5 * 60 * 1000, // 5 min — earthquake data updates frequently
+});
+const waterApi = createClient({
+    baseUrl: "https://waterservices.usgs.gov/nwis",
+    name: "usgs-water",
+    rateLimit: { perSecond: 5, burst: 10 },
+    cacheTtlMs: 15 * 60 * 1000, // 15 min
+});
+// ─── Reference Data ──────────────────────────────────────────────────
+/** Common USGS water parameter codes. */
+export const WATER_PARAMS = {
+    "00060": "Discharge (cubic feet per second)",
+    "00065": "Gage height (feet)",
+    "00010": "Temperature, water (°C)",
+    "00400": "pH",
+    "00300": "Dissolved oxygen (mg/L)",
+    "00095": "Specific conductance (µS/cm)",
+    "00045": "Precipitation (inches)",
+    "72019": "Depth to water level (feet below land surface)",
+};
+/** Earthquake alert levels. */
+export const ALERT_LEVELS = {
+    green: "Limited impact — no damage expected",
+    yellow: "Regional impact — some damage possible",
+    orange: "National/international impact — significant damage likely",
+    red: "Massive impact — extensive damage and casualties expected",
+};
+// ─── Public API ──────────────────────────────────────────────────────
+/**
+ * Search for earthquakes using USGS FDSN Event Web Service.
+ *
+ * Example:
+ *   const quakes = await searchEarthquakes({ minmagnitude: 5, starttime: "2024-01-01" });
+ *   const nearby = await searchEarthquakes({ latitude: 37.77, longitude: -122.42, maxradiuskm: 100 });
+ */
+export async function searchEarthquakes(opts) {
+    const params = {
+        format: "geojson",
+        starttime: opts.starttime,
+        endtime: opts.endtime,
+        minmagnitude: opts.minmagnitude,
+        maxmagnitude: opts.maxmagnitude,
+        mindepth: opts.mindepth,
+        maxdepth: opts.maxdepth,
+        latitude: opts.latitude,
+        longitude: opts.longitude,
+        maxradiuskm: opts.maxradiuskm,
+        minlatitude: opts.minlatitude,
+        maxlatitude: opts.maxlatitude,
+        minlongitude: opts.minlongitude,
+        maxlongitude: opts.maxlongitude,
+        limit: opts.limit ?? 20,
+        orderby: opts.orderby ?? "time",
+        alertlevel: opts.alertlevel,
+    };
+    return earthquakeApi.get("/fdsnws/event/1/query", params);
+}
+/**
+ * Count earthquakes matching the given criteria.
+ *
+ * Example:
+ *   const count = await countEarthquakes({ minmagnitude: 4, starttime: "2024-01-01" });
+ */
+export async function countEarthquakes(opts) {
+    const params = {
+        format: "geojson",
+        starttime: opts.starttime,
+        endtime: opts.endtime,
+        minmagnitude: opts.minmagnitude,
+        maxmagnitude: opts.maxmagnitude,
+        latitude: opts.latitude,
+        longitude: opts.longitude,
+        maxradiuskm: opts.maxradiuskm,
+    };
+    return earthquakeApi.get("/fdsnws/event/1/count", params);
+}
+/**
+ * Get the latest significant earthquakes (last 30 days, magnitude 4.5+).
+ */
+export async function getSignificantEarthquakes() {
+    return earthquakeApi.get("/earthquakes/feed/v1.0/summary/significant_month.geojson");
+}
+/**
+ * Get USGS water data (streamflow, water level, temperature, etc.) from monitoring sites.
+ *
+ * Example:
+ *   const data = await getWaterData({ sites: "01646500", parameterCd: "00060" });
+ *   const data = await getWaterData({ stateCd: "CA", parameterCd: "00060", period: "P7D" });
+ */
+export async function getWaterData(opts) {
+    const params = {
+        format: "json",
+        sites: opts.sites,
+        stateCd: opts.stateCd,
+        countyCd: opts.countyCd,
+        huc: opts.huc,
+        parameterCd: opts.parameterCd ?? "00060",
+        period: opts.period ?? "P1D",
+        startDT: opts.startDT,
+        endDT: opts.endDT,
+        siteType: opts.siteType,
+        siteStatus: opts.siteStatus ?? "active",
+    };
+    // Remove period if explicit date range is given
+    if (opts.startDT || opts.endDT)
+        delete params.period;
+    return waterApi.get("/iv/", params);
+}
+/**
+ * Search for USGS water monitoring sites.
+ *
+ * Example:
+ *   const sites = await searchWaterSites({ stateCd: "CA", siteType: "ST" });
+ */
+export async function searchWaterSites(opts) {
+    const params = {
+        format: "rdb",
+        stateCd: opts.stateCd,
+        countyCd: opts.countyCd,
+        huc: opts.huc,
+        siteType: opts.siteType ?? "ST",
+        siteStatus: opts.siteStatus ?? "active",
+        hasDataTypeCd: opts.hasDataTypeCd ?? "iv",
+        siteOutput: "expanded",
+    };
+    // RDB is tab-delimited but easier to parse than the alternatives
+    return waterApi.get("/site/", params);
+}
+/**
+ * Get USGS daily value water data (historical daily averages).
+ * Unlike instantaneous values (iv), these are aggregated daily means.
+ *
+ * Example:
+ *   const data = await getDailyWaterData({ sites: '01646500', parameterCd: '00060', period: 'P30D' });
+ *   const data = await getDailyWaterData({ stateCd: 'CA', parameterCd: '00065', startDT: '2024-01-01', endDT: '2024-12-31' });
+ */
+export async function getDailyWaterData(opts) {
+    const params = {
+        format: "json",
+        sites: opts.sites,
+        stateCd: opts.stateCd,
+        countyCd: opts.countyCd,
+        huc: opts.huc,
+        parameterCd: opts.parameterCd ?? "00060",
+        period: opts.period ?? "P30D",
+        startDT: opts.startDT,
+        endDT: opts.endDT,
+        siteType: opts.siteType,
+        siteStatus: opts.siteStatus ?? "active",
+        statCd: opts.statCd,
+    };
+    if (opts.startDT || opts.endDT)
+        delete params.period;
+    return waterApi.get("/dv/", params);
+}
+/** Clear all USGS caches. */
+export function clearCache() {
+    earthquakeApi.clearCache();
+    waterApi.clearCache();
+}
+//# sourceMappingURL=usgs.js.map