get-historical-observations-by-reporting-area-by-zip-code
Retrieve historical air quality index (AQI) values and categories for a specific reporting area using a Zip code and date. Supports output in CSV, JSON, or XML formats.
Instructions
Get historical AQI values and categories for a reporting area by Zip code.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01 | |
| distance | No | If no reporting area is associated with the Zip code, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150 | |
| format | Yes | Format of the payload file returned. Example: application/json | |
| zipCode | Yes | Zip code to get the historical observations for. Example: 94954 |
Implementation Reference
- MCP tool handler that invokes the AirNow API and returns the response as text content or an error.async (params) => { const result = await airnowApi.fetchHistoricalObservationsByReportingAreaByZipCode( params ); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch historical observations data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; }
- Zod schema defining the input parameters for the tool.zipCode: z .string() .describe( "Zip code to get the historical observations for. Example: 94954" ), date: z .string() .describe( "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01" ), format: z .enum(["text/csv", "application/json", "application/xml"]) .describe( "Format of the payload file returned. Example: application/json" ), distance: z .string() .optional() .describe( "If no reporting area is associated with the Zip code, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150" ), },
- Function that registers the tool with the MCP server, including name, description, schema, and handler.export const registerHistoricalObservationsByZipCode = (server: McpServer): void => { server.tool( "get-historical-observations-by-reporting-area-by-zip-code", "Get historical AQI values and categories for a reporting area by Zip code.", { zipCode: z .string() .describe( "Zip code to get the historical observations for. Example: 94954" ), date: z .string() .describe( "Date to get the historical observations for. Format: YYYY-MM-DD. Example: 2012-02-01" ), format: z .enum(["text/csv", "application/json", "application/xml"]) .describe( "Format of the payload file returned. Example: application/json" ), distance: z .string() .optional() .describe( "If no reporting area is associated with the Zip code, historical observations from a nearby reporting area within this distance (in miles) will be returned, if available. Example: 150" ), }, async (params) => { const result = await airnowApi.fetchHistoricalObservationsByReportingAreaByZipCode( params ); if (result === null) { return { content: [ { type: "text", text: "Failed to fetch historical observations data from AirNow API.", }, ], isError: true, }; } return { content: [ { type: "text", text: result, }, ], }; } ); };
- src/airnow-api.ts:63-72 (helper)Core helper function that performs the HTTP request to the AirNow API for historical observations by zip code.export async function fetchHistoricalObservationsByReportingAreaByZipCode(params: Record<string, string>): Promise<string | null> { const endpoint = 'aq/observation/zipcode/historical/'; const queryParams = new URLSearchParams(); queryParams.append('zipCode', params.zipCode); queryParams.append('date', params.date); queryParams.append('format', params.format); if (params.distance) queryParams.append('distance', params.distance); return airnowGet(endpoint, queryParams); }
- src/tools/index.ts:10-22 (registration)Imports and calls the register function as part of registering all tools.import { registerHistoricalObservationsByZipCode } from "./historical-observations-by-reporting-area-by-zip-code.js"; import { registerObservationsByBoundingBox } from "./observations-by-monitoring-site-by-geographic-bounding-box.js"; export const registerTools = (server: McpServer): void => { registerContourMapsByBoundingBoxCombined(server); registerContourMapsByBoundingBoxOzone(server); registerContourMapsByBoundingBoxPM25(server); registerCurrentObservationsByZipCode(server); registerCurrentObservationsByLatLong(server); registerForecastByLatLong(server); registerForecastByZipCode(server); registerHistoricalObservationsByLatLong(server); registerHistoricalObservationsByZipCode(server);